tcov(1)

名前
tcov - ソースコードテストカバレージ解析用の文単位のプロファイル

形式
tcov [ -a ] [ -n ] [ -o filename ] [ -p oldpath newpath ]
[ -x dir ] files ...

機能説明

tcov は、コンパイルしたプログラムのテストカバレージ解析を生成します。 tcov は、引数としてソースファイルを取り、注釈付きのソースリストを 生成します。出力上、コードの各基本ブロック (または、tcov に -a オプションを指定する場合は、各行) の先頭には、 そのセグメント (行) の実行回数が示されます。 また、実行されなかった行の先頭には、#### が示されます。 基本ブロックは、分岐のないコードの隣接するセクションです。基本ブロックの各文は、同じ回数実行されます。

tcov を使用するには、プログラムは -xprofile=tcov または -xa コンパイラオプションでコンパイルしなければなりません。

tcov カバレージ解析には 2 つの実装があります。 -xa オプションでコンパイルすると、オリジナルの「古いスタイルの」 カバレージ解析用のオブジェクトコードが準備されます。

-xprofile=tcov コンパイラオプションでコンパイルし、tcov -x dir オプションを使用すると、拡張された「新しいスタイルの」カバレージ 解析が呼び出されます。

どちらの場合も、ソースファイルのコピーと (そのマージンに) 文の 実行回数が出力されます。

「古いスタイル」の tcov カバレージ解析:
-xa コンパイラオプションでプログラムをコンパイルします。これにより、 コンパイルしたソースファイルごとに、ファイル $TCOVDIR/file.d が生成されます。 環境変数 TCOVDIR を設定していない場合、.d ファイルは現在のディレクトリに格納されます。

プログラムの実行。プログラムのコンパイル時に、.d ファイルは更新されます。コンパイルが正常に終了しなければ、 カバレージ解析は生成されません。ソースファイル付き カバレージ解析を表示するには、tcov をソースファイルで 実行します。コンパイルしたソースファイルごとの注釈付き解析 ファイルの名前は、$TCOVDIR/file.tcov です。

tcov が生成する出力は、文または文のグループのそれぞれが その実行の中で実際に何回実行されたかを示します。tcov オプション -a を指定すると、実行されなかった文の 左側に ####-> のマークが付きます。

「新しいスタイルの」拡張された tcov 解析:
tcov を使用するときは、 -xprofile=tcov でプログラムをコンパイルすることを推奨します。プログラムを実行するとき、 カバレージデータは program.profile/tcovd (program は 実行可能ファイルの名前) に格納されます。たとえば、実行可能ファイルが a.out の場合、ファイル a.out.profile/tcovd が作成されます。

コンパイルとリンクを別の段階で行う場合、コンパイルとリンクでは 同じ -xprofile オプションを使用し、ld ではなく、 コンパイラでリンクを行います。

tcov -x dir file ... を各ソースファイルで実行すると、 カバレージ解析とそのソースファイルがマージされたファイル file.tcov が現在のディレクトリに作成されます。 また、ソースファイルごとに別の .tcov ファイルも作成されます。

環境変数 SUN_PROFDATA と SUN_PROFDATA_DIR を 使用すると、中間データ収集ファイルを保存する場所を指定できます。 古いスタイルの tcov の場合、中間データ収集ファイルは *.d ファイルで、新しいスタイルの tcov の場合は *.tcovd ファイルです (後述の「環境」を参照)。

これ以降に何回も実行すると、カバレージデータは program.profile/tcovd ファイルに累積されます。 各オブジェクトファイルのデータは、再コンパイル後、 最初にプログラムを実行するとゼロにされます。全プログラムのデータは、 tcovd ファイルを削除するとゼロにされます。

オプション

-a  各文の実行回数を表示します。 -a を指定しない場合、 コードの各基本ブロックにおける先頭の文の実行回数だけが 表示されます。

-n  実行回数が最も多い n 個の文の行番号とそれぞれの実行回数を示すテーブルを表示します。

-o filename
    file.tcov の代わりにファイル名 filename へ出力できます。 filename が "-" である場合は、 file.tcov の代わりに標準出力に出力されます。 このオプションは TCOVDIR 環境変数に指定されたディレクトリを変更します (後述の「環境」を参照)。

-p originalpath newpath
    コンパイルした時と tcov を実行する時のソースファイルのパスが違う場合 -x オプションは混乱を招く恐れがあります。 同じディレクトリに対してマウントするポイント が違う 2 つのマシンを使用している場合に、 この状況はよく起こります。 このオプションを使用すると、 コンパイル時に originalpath で修飾していたすべての ソースファイルを tcov の実行時には newpath で修飾するように tcov に指示できます。 -p オプションは好きな数だけ指定できます。

-x dir
    「新しいスタイル」の tcov カバレージ解析。 ソースファイルは -xprofile=tcov コンパイラフラグでコンパイルしなければなりません。 dir は、カバレージファイルが格納されるディレクトリの名前です。 通常は、この名前は program.profile/ (program はコンパイルした実行可能ファイルの名前) です (たとえば、a.out.profile)。

    -x dir を指定しない場合、「古いスタイル」の tcov カバレージが仮定されます。

使用例
古いスタイルの tcov:

     demo% cc -o myprog -a alpha.c beta.c gamma.c
     demo% myprog      program execution
     demo% tcov -a alpha.c beta.c gamma.c
     demo% cat alpha.tcov beta.tcov gamma.tcov

新しい拡張された tcov:

     demo% cc -o myprog -xprofile=tcov alpha.c beta.c gamma.c
     demo% myprog      program execution
     demo% tcov -x myprog.profile alpha.c beta.c gamma.c
     demo% cat alpha.c.tcov beta.c.tcov gamma.c.tcov

環境

TCOVDIR
    「古いスタイル」のカバレージ解析 ( -x オプションなし)。コンパイル時に TCOVDIR 環境変数を設定する場合、 この環境変数は file.d ファイルが書き込まれる場所を指定します。 tcov 実行時には、file.d が存在する場所と file.tcov カバレージ解析ファイルが書き込まれる場所を指定します。 ユーザーによるプログラムの実行時には効果がありません。

「新しいスタイル」のカバレージ解析
    ( -x オプション付き)。次の SUN_PROFDATA_DIR と同じです。

SUN_PROFDATA_DIR/SUN_PROFDATA
    「新しいスタイル」のカバレージ解析。これらの環境変数を設定する場合、tcov はパフォーマンスカバレージデータを $SUN_PROFDATA_DIR/$SUN_PROFDATA/ にあるファイルに書き込みます。

    設定する場合、$SUN_PROFDATA は、program.profile の代わりに、tcov が読み取るディレクトリの名前として使用されます。 この場合、適切な tcov コマンドは次のようになります。 be:

        demo% tcov -x $SUN_PROFDATA source_files...

    SUN_PROFDATA_DIR を設定する場合、現在のディレクトリの代わりに、 tcov がカバレージファイルを探すディレクトリとして使用されます。 TCOVDIR と SUN_PROFDATA_DIR の両方を設定する場合、 警告が発行され、SUN_PROFDATA_DIR が使用されます。

ファイル

-x フラグがない場合 (古いスタイルの tcov):
    file.d コンパイルされたソースファイル用にコンパイラが作成した 入力テストカバレージデータファイル

    file.tcov    出力テストカバレージ解析一覧ファイル

-x フラグがある場合 (新しいスタイルの tcov):
    myprog.profile/tcovd 入力テストカバレージデータファイル

    file.c.tcov 出力テストカバレージ解析一覧ファイル (ファイル拡張子を含む ： alpha.c.tcov)

    上記 SUN_PROFDATA_DIR と SUN_PROFDATA 環境変数も 参照してください。

関連項目
acc(1)、 (SPARC プラットフォームのみ) cc(1)、 CC(1)、 f77(1)、 f95(1) (SPARC プラットフォームのみ) gprof(1)、 prof(1)、 exit(2)

診断

premature end of file
    文をまったく含まないルーチンが検出されると、 このメッセージが出力されます。

使用上の留意点
マルチプロセッサ/マルチスレッド化されたプログラムで tcov を使用する場合:
-a (または -xa ) オプションでコンパイルした MP/MT プログラムを実行すると、 予想外の結果が生成されます。 -xprofile=tcov オプションは、MP/MT プログラムでも使用できますが、 tcov の出力は、ゼロまたは非ゼロの値の場合だけに有効です。 実行回数は正しくありません。

基本ブロック数は、 unsigned int によって表現される値を超えることができません。

tcov は、#line および #file 命令を含む ファイルをサポートしません。

解析対象のプログラムが exit(2) を呼び出すか、正常に制御を戻していないと、 カバレージ情報は .d ファイルに保存されません。