doc/ja_JP.eucJP/man/man3/devstat.3

.\"
.\" Copyright (c) 1998, 1999 Kenneth D. Merry.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" %FreeBSD: src/lib/libdevstat/devstat.3,v 1.7.2.8 2001/12/17 10:08:29 ru Exp %
.\"
.\" $FreeBSD$
.Dd May 21, 1998
.Dt DEVSTAT 3
.Os
.Sh 名称
.Nm devstat ,
.Nm getnumdevs ,
.Nm getgeneration ,
.Nm getversion ,
.Nm checkversion ,
.Nm getdevs ,
.Nm selectdevs ,
.Nm buildmatch ,
.Nm compute_stats ,
.Nm compute_etime
.Nd デバイス統計ユーティリティライブラリ
.Sh ライブラリ
.Lb libdevstat
.Sh 書式
.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
.Sh 解説
.Nm
ライブラリは、カーネル
.Xr devstat 9
インタフェースを処理するのに
便利な関数のライブラリです。カーネル
.Xr devstat 9
インタフェースは、
.Xr sysctl 3
によってユーザがアクセスできます。
.Pp
.Fn getnumdevs
は、カーネル内の
.Nm
サブシステムに登録された
デバイスの数を返します。
.Pp
.Fn getgeneration
は、カーネル内のデバイス
.Nm
リストの現在の世代を
返します。
.Pp
.Fn getversion
は、現在のカーネル
.Nm
デバイスバージョンを返します。
.Pp
.Fn checkversion
は、カーネル
.Nm
バージョンに対して
ユーザランド devstat
をチェックします。
2 つが同一の場合、0 が返されます。そうでない場合は、
.Va devstat_errbuf
に該当するエラーを表示し -1 を返します。
.Pp
.Fn getdevs
は、デバイスと統計の現在のリストを取り出して、指定された
.Va statinfo
構造に入れます。
.Va statinfo
構造は
.Aq Pa devstat.h
にあります。
.Bd -literal -offset indent
struct statinfo {
	long		cp_time[CPUSTATES];
	long		tk_nin;
	long		tk_nout;
	struct devinfo	*dinfo;
	struct timeval	busy_time;
};
.Ed
.Pp
.Fn getdevs
は、
.Va statinfo
構造が割り当てられることを期待し、また、
.Fn getdevs
の起動の前に
.Va dinfo
サブエレメントが割り当てられて 0 で初期化されることも期待します。
.Va dinfo
サブエレメントは、呼び出しと呼び出しの間の状態を格納するために使用され、
最初の
.Fn getdevs
呼び出しの後には変更してはなりません。
.Va dinfo
サブエレメントには次のエレメントが入っています。
.Bd -literal -offset indent
struct devinfo {
	struct devstat	*devices;
	u_int8_t	*mem_ptr;
	long		generation;
	int		numdevs;
};
.Ed
.Pp
.Va kern.devstat.all sysctl
変数には、
.Nm
構造の配列が入っていますが、配列の先頭は現在の
.Nm
世代です。世代がバッファの先頭にある理由は、
.Nm
統計にアクセスしているユーザランドソフトウェアが自動的に
統計情報および対応する世代番号の両方を不可分に得るようにするためです。
クライアントソフトウェアが別の
.Nm sysctl
変数 (これは便宜のために利用できます) を通じて世代番号を得ることを
強制された場合、デバイスのリストは、クライアントが世代を得る時刻と、
クライアントがデバイスリストを得る時刻の間で変化する可能性があります。
.Pp
.Va devinfo
構造の
.Va mem_ptr
サブエレメントは、割り振られたメモリを指すポインタであり、必要であれば、
.Fn getdevs
によってサイズを変更されます。
.Va devinfo
構造のデバイスサブエレメントは基本的に、
.Va kern.devstat.all
.Nm sysctl
変数から
.Nm
構造の配列の先頭を指すポインタです。
.Va devinfo
構造の世代
サブエレメントには、
.Va kern.devstat.all
.Nm sysctl
変数からの世代番号が含まれています。
.Va devinfo
構造の
.Va numdevs
サブエレメントには、カーネル
.Nm
サブシステムで登録されたデバイスの現在の番号が入っています。
.Pp
.Fn selectdevs
は、規準の数を基礎にして表示するデバイスを選択します。
.Bl -tag -width flag
.It 指定デバイス
指定されたデバイスは最初の選択優先順位です。これらは、一般に、
ユーザにより名前により指定されたデバイス、たとえば、
da0, da1, cd0 です。
.It マッチパターン
これらのパターンユーザ入力から
.Fn buildmatch
によって生成されたパターンマッチング式です。
.It 性能
性能モードが有効な場合、デバイスは、
.Fn selectdevs
に渡される
.Va device_selection
構造内の
.Va bytes
フィールドを基礎にしてソートされます。
.Va bytes
値は、現時点では、ユーザが保守する必要があります。将来的には、これは
.Nm
ライブラリルーチンで行われる可能性があります。デバイスが名前または
パターンによって選択されていない場合、性能追跡コードがシステム内の
各デバイスを選択し、これらを性能によってソートします。デバイスが名前または
パターンによって選択されている場合、性能追跡コードはこれらの選択を尊重し、
選択されたデバイスの間でだけソートします。
.It devstat リスト内の順序
選択モードが DS_SELECT_ADD に設定され、しかも
.Va maxshowdevs
未満のデバイスが選択されている場合、
.Fn selectdevs
が自動的に
.Va maxshowdevs
デバイスをセットアップします。
.El
.Pp
.Fn selectdevs
は、次の 4 つのモードで選択を行います。
.Bl -tag -width DS_SELECT_ADDONLY
.It DS_SELECT_ADD
追加モードで、
.Fn selectdevs
は、名前または一致パターンによって指定された
選択されていないデバイスを選択します。また、これは
.Nm
の順序でさらにデバイスを選択します。選択したデバイスの数が
.Va maxshowdevs
に等しくなるまで、またはすべてのデバイスが選択されるまでです。
.It DS_SELECT_ONLY
only モードで、
.Fn selectdevs
は、現在の選択肢をすべてクリアし、
名前または一致するパターンで指定されたデバイスだけを選択します。
.It DS_SELECT_REMOVE
除去モードで、
.Fn selectdevs
は、名前または一致パターンによって指定されたデバイスを除去します。
追加デバイスは選択しません。
.It DS_SELECT_ADDONLY
追加のみモードで、
.Fn selectdevs
は、名前または一致する
パターンで指定された選択されないデバイスを選択します。この点では、これは
追加モードと同一です。しかし、指定された以外のデバイスは選択しません。
.El
.Pp
すべての選択モードで、
.Fn selectdevs
は、
.Va maxshowdevs
デバイスを越えるデバイスは選択しません。1 つの例外は、
.Dq top
モードにあり、デバイスが選択されていないときです。この場合、
.Fn selectdevs
は、システム内の各デバイス
を選択します。クライアントプログラムは、特定のデバイスに注意を払うかどうか
決定するときに、選択の順序に注意を払う必要があります。これはまずい
動作であり、さらに考慮する必要があると考えられます。
.Pp
.Fn selectdevs
は、クライアントによって渡された
.Va dev_select
構造の割り当てとサイズ変更を処理します。
.Fn selectdevs
は、
.Va numdevs
フィールドと
.Va current_generation
フィールドを使用して、現在の
.Nm
世代とデバイスの数を追跡します。
.Va num_selections
が
.Va numdevs
と同じでない場合、または
.Va select_generation
が
.Va current_generation
と同じでない場合、
.Fn selectdevs
は、選択リストを必要に応じてサイズ変更し、選択配列を初期化し直します。
.Pp
.Fn buildmatch
は、コンマで区切られた一致ストリングを取り、
.Fn selectdevs
が理解する
\fBdevstat_match\fR 構造にコンパイルします。一致ストリングの形式は
次のとおりです。
.Pp
.Bd -literal -offset indent
device,type,if
.Ed
.Pp
.Fn buildmatch
は、必要に応じて、一致リストの割り当てと再割り当てを
処理します。現時点で既知の一致タイプには次のものが含まれます。
.Pp
.Bl -tag -width indent -compact
.It デバイスタイプ:
.Bl -tag -width 9n -compact
.It da
ダイレクトアクセスデバイス
.It sa
シーケンシャルアクセスデバイス
.It printer
プリンタ
.It proc
プロセッサデバイス
.It worm
書き込み 1 回読み取り複数デバイス (Write Once Read Multiple devices)
.It cd
CD デバイス
.It scanner
スキャナデバイス
.It optical
光学メモリデバイス
.It changer
媒体変更 (Medium Changer) デバイス
.It comm
通信デバイス
.It array
ストレージ配列デバイス
.It enclosure
囲みサービスデバイス (Enclosure Services devices)
.It floppy
フロッピデバイス
.El
.Pp
.It インタフェース:
.Bl -tag -width 9n -compact
.It IDE
統合ドライブ電子工学デバイス (Integrated Drive Electronics devices)
.It SCSI
小型コンピュータシステムインタフェースデバイス
.It other
他のデバイスインタフェース
.El
.Pp
.It パススルー:
.Bl -tag -width 9n -compact
.It pass
パススルーデバイス
.El
.El
.Pp
.Fn compute_stats
は、さまざまなデバイス統計を得るための簡単な方法です。
.Va current
と
.Va etime
の 2 つの引数が必須です。他の各引数はオプションです。
ほとんどのアプリケーションの場合、ユーザは
.Va current
と
.Va previous
の
.Nm
構造の両方を指定したいと思うものです。指定期間に渡って統計が
計算できるようにするためにです。インスタンスによっては、システム起動からの
統計を計算するために、ユーザは
.Va previous
の引数について NULL ポインタを渡すことがあります。その場合、
.Fn compute_stats
は、
.Va current
の構造内の合計状態を使用して、
.Va etime
時間に渡る統計を計算します。
.Fn compute_stats
が計算する可能性のある各種統計は、関数宣言自体で主に説明する
必要がありますが、完全性を期するために、変数名のリストとそれに入れられる
統計を示します。
.Bl -tag -width transfers_per_second
.It total_bytes
.Va previous
の取得と
.Va current
の取得の間で、読み取りと書き込みの
両方が、指定デバイスで転送されるバイトの合計数です。
.Va previous
が NULL の場合、結果は
.Va current
で与えられる合計の読み取りと書き込みです。
.It total_transfers
.Va previous
の取得と
.Va current
の取得の間で完了される転送の合計数です。以前が NULL の場合、結果は
.Va current
内にリストされるトランザクションの合計数です。
.It total_blocks
基本的に
.Va total_bytes
をデバイスブロックサイズで除算したものです。ブロックサイズが
.Sq 0
としてリストされている場合、デバイスブロックサイズは、
デフォルトで 512 バイトになります。
.It kb_per_transfer
測定期間の間の転送ごとの平均 KB 数です。
.It transfers_per_second
秒ごとの転送の平均数です。
.It mb_per_second
秒ごとの平均 MB です。
.It locks_per_second
秒ごとの平均ブロックです。デバイスブロックサイズが
.Sq 0
の場合、デフォルトのブロックサイズ 512 バイトが代わりに使用されます。
.It ms_per_transaction
トランザクションごとの平均ミリ秒数です。
.El
.Pp
.Fn compute_etime
は、2 つの
.Va timeval
構造の間の秒単位の違いを検出する簡単な方法です。これは、
.Fn getdevs
関数 (
.Va statinfo
構造体内 ) が、現在の
.Nm
リストを取り出すたびに、
.Fn getdevs
関数が記録した時刻とともに最も一般的に使用されます。
.Sh 戻り値
.Fn getnumdevs ,
.Fn getgeneration
、および
.Fn getversion
は、指示された \fBsysctl\fR 変数を返します。
変数を取り出すときにエラーがあった場合は -1 を返します。
.Pp
.Fn checkversion
は、カーネルとユーザランド devstat バージョンが一致する場合、
0 を返します。一致しない場合、 -1 を返します。
.Pp
.Fn getdevs
と
.Fn selectdevs
は、エラーの場合は -1 を返し、エラーがない場合は 0 を返し、
デバイスリストまたは選択したデバイスが変化している場合は 1 を返します。
.Fn getdevs
からの戻り値が 1 であるのは、
.Fn selectdevs
の再実行の
ヒントです。デバイスリストが変化しているからです。
.Pp
.Fn buildmatch
はエラーの場合は -1 、エラーがない場合は 0 を返します。
.Pp
.Fn compute_stats
はエラーの場合は -1 、成功の場合は 0 を返します。
.Pp
.Fn compute_etime
計算済みの経過時間を返します。
.Pp
.Nm
ライブラリ関数の 1 つからエラーが返された場合、一般に、エラーの
理由がグローバルストリング
.Va devstat_errbuf
に印刷されます。
.Va devstat_errbuf
の長さは
.Dv DEVSTAT_ERRBUF_SIZE
キャラクタです。
.Sh 関連項目
.Xr systat 1 ,
.Xr iostat 8 ,
.Xr rpc.rstatd 8 ,
.Xr vmstat 8 ,
.Xr devstat 9
.Sh 歴史
.Nm
統計システムは最初に
.Fx 3.0
に現れました。
.Sh 作者
.An Kenneth Merry Aq ken@FreeBSD.org
.Sh バグ
.Fn getdevs ,
.Fn selectdevs
、および
.Fn buildmatch
によって割り振られたメモリを
割り当て解除するためのインタフェースがおそらくあるはずです。
.Pp
.Fn selectdevs
は、デバイスが以前に選択されていない場合、
.Dq top
モードでは、
.Va maxshowdevs
デバイスより多くを選択することはおそらくできません。
.Pp
このライブラリのほとんどのクライアントについて行われる統計バッファスワップ
を実行するための関数がおそらくあるはずです。
.Pp
.Va statinfo
構造と
.Nm devinfo
構造は、クリーンアップし、もう少し考える必要があります。