jpman project specific RCS keyword (jpman %Id) is obsolete, after manual entries are stored in freefall CVS repository. This old Id is useless and more worse it confuses users and bug reporters. So, this old Id is removed. Submitted by:jpman project <man-jp@jp.FreeBSD.org>
525 lines
13 KiB
Groff
525 lines
13 KiB
Groff
.\"
|
|
.\" Copyright (c) 1998 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.
|
|
.\"
|
|
.\" %Id: devstat.3,v 1.3 1999/01/06 04:59:53 obrien Exp %
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.Dd May 21, 1998
|
|
.Dt DEVSTAT 3
|
|
.Os FreeBSD 3.0
|
|
.Sh 名称
|
|
.Nm devstat
|
|
.Nd デバイス統計ユーティリティライブラリ
|
|
.Sh 書式
|
|
.Fd #include <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 devstat
|
|
ライブラリは、カーネル
|
|
.Xr devstat 9
|
|
インタフェースを処理するのに
|
|
便利な関数のライブラリです。カーネル
|
|
.Xr devstat 9
|
|
インタフェースは、
|
|
.Xr sysctl 3
|
|
によってユーザーがアクセスできます。
|
|
.Pp
|
|
.Fn getnumdevs
|
|
は、カーネル内の
|
|
.Nm devstat
|
|
サブシステムとともに登録された
|
|
デバイスの番号を返します。
|
|
.Pp
|
|
.Fn getgeneration
|
|
は、カーネル内のデバイス
|
|
.Nm devstat
|
|
リストの現在の世代を
|
|
返します。
|
|
.Pp
|
|
.Fn getversion
|
|
は、現在のカーネル
|
|
.Nm devstat
|
|
デバイスバージョンを返します。
|
|
.Pp
|
|
.Fn checkversion
|
|
は、カーネル
|
|
.Nm devstat
|
|
バージョンに対して
|
|
userland devstat
|
|
をチェックします。
|
|
2 つが同一の場合、ゼロが返されます。そうでない場合は、
|
|
.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
|
|
構造が割り振られるのを予期し、また、定刻より早く
|
|
.Va dinfo
|
|
サブエレメントが割り振られるのも予期します。
|
|
.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 devstat
|
|
構造の配列が入っていますが、配列の先頭は現在の
|
|
.Nm devstat
|
|
世代です。世代がバッファの先頭にある理由は、
|
|
.Nm devstat
|
|
統計にアクセスしている userland ソフトウェアが自動的に
|
|
統計情報および対応する世代番号の両方を自動的に得るようにするためです。
|
|
クライアントソフトウェアが別の
|
|
.Nm sysctl
|
|
変数 ( これは便宜のために利用できます ) を通じて世代番号を得ることを
|
|
強制された場合、デバイスのリストは、クライアントが世代を得る時刻と、
|
|
クライアントがデバイスリストを得る時刻の間で変化する可能性があります。
|
|
.Pp
|
|
.Va devinfo
|
|
構造の
|
|
.Va mem_ptr
|
|
サブエレメントは、割り振られたメモリを指すポインタであり、必要であれば、
|
|
.Fn getdevs
|
|
によってサイズを変更されます。
|
|
.Va devinfo
|
|
構造のデバイスサブエレメントは基本的に、
|
|
.Va kern.devstat.all
|
|
.Nm sysctl
|
|
変数から
|
|
.Nm devstat
|
|
構造の配列の先頭を指すポインタです。
|
|
.Nm devinfo
|
|
構造の世代
|
|
サブエレメントには、
|
|
.Va kern.devstat.all
|
|
.Nm sysctl
|
|
変数からの世代番号が含まれています。
|
|
.Va devinfo
|
|
構造の
|
|
.Va numdevs
|
|
サブエレメントには、カーネル
|
|
.Nm devstat
|
|
サブシステムで登録されたデバイスの現在の番号が入っています。
|
|
.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 devstat
|
|
ライブラリルーチンで行われる可能性があります。デバイスが名前または
|
|
パターンによって選択されていない場合、性能追跡コードがシステム内の
|
|
各デバイスを選択し、これらを性能によってソートします。デバイスが名前または
|
|
パターンによって選択されている場合、性能追跡コードはこれらの選択を尊重し、
|
|
選択されたデバイスの間でだけソートします。
|
|
.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 devstat
|
|
の順序でさらにデバイスを選択します。選択したデバイスの数が
|
|
.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 devstat
|
|
世代とデバイスの数を追跡します。
|
|
.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 123456789 -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 123456789 -compact
|
|
.It IDE
|
|
統合ドライブ電子工学デバイス (Integrated Drive Electronics devices)
|
|
.It SCSI
|
|
小型コンピュータシステムインタフェースデバイス
|
|
.It other
|
|
他のデバイスインタフェース
|
|
.El
|
|
.Pp
|
|
.It パススルー:
|
|
.Bl -tag -width 123456789 -compact
|
|
.It pass
|
|
パススルーデバイス
|
|
.El
|
|
.El
|
|
.Pp
|
|
.Fn compute_stats
|
|
は、さまざまなデバイス統計を得るための簡単な方法です。
|
|
.Va current
|
|
と
|
|
.Va etime
|
|
の 2 つの引数が必須です。他の各引数はオプションです。
|
|
ほとんどのアプリケーションの場合、ユーザは
|
|
.Va current
|
|
と
|
|
.Va previous
|
|
の
|
|
.Nm devstat
|
|
構造の両方を指定したいと思うものです。指定期間に渡って統計が
|
|
計算できるようにするためにです。インスタンスによっては、システム起動からの
|
|
統計を計算するために、ユーザは
|
|
.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 devstat
|
|
リストを取り出すたびに、
|
|
.Fn getdevs
|
|
関数が記録した時刻とともに最も一般的に使用されます。
|
|
.Sh 戻り値
|
|
.Fn getnumdevs ,
|
|
.Fn getgeneration
|
|
、および
|
|
.Fn getversion
|
|
は、指示された \fBsysctl\fR 変数を返します。
|
|
変数を取り出すときにエラーがあった場合は -1 を返します。
|
|
.Pp
|
|
.Fn checkversion
|
|
は、カーネルと userland 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 devstat
|
|
ライブラリ関数の 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 devstat
|
|
統計システムは最初に
|
|
.Fx 3.0
|
|
に現れました。
|
|
.Sh 作者
|
|
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
|
|
構造は、クリーンアップし、もう少し考える必要があります。
|