cscope(1)

名前
cscope - 対話形式による C プログラムの検査

形式
cscope [options] files...

機能説明
cscope は、コードの特定の要素について C 言語のソースファイルを 検査するための画面処理用ツールです。

デフォルトでは、現作業ディレクトリに存在する C ( .c と .h)、 lex (.l)、 yacc (.y) のソースファイルを検査します。 また、起動時にコマンド行で検査対象にするソースファイルの 名前を指定することができます。 どちらの場合でも、現作業ディレクトリで #include ファイルが見つからなければ、 cscope は標準のディレクトリで検索を行います。 cscope はシンボル相互参照 (デフォルトでは cscope.out ) を使って、 ファイル内の関数、関数呼び出し、マクロ、変数、前処理シンボルの 場所を突き止めます。

検査対象のプログラムを構成するソースファイルに対して初めて使用されたとき、 cscope はシンボル相互参照を作成します。 それ以降の呼び出しでは、ソースファイルの内容が変更されているか、 または指定されたソースファイルが異なっている場合にかぎり、 相互参照を再作成します。 相互参照を再作成する場合は、 変更がないファイルのデータは古い相互参照からコピーされるため、 初めて作成する場合よりも高速になります。

次のオプションを自由に組み合わせることができます。

-b  相互参照の作成だけを行います。

-C  検索時に大文字 / 小文字を無視します。

-c  相互参照ファイルで ASCII 文字だけを使用します。 すなわち、データを圧縮しません。

-d  相互参照を更新しません。

-e  1 つのファイルの処理後、 次のファイルを処理する前に現れる ^e コマンド・プロンプトを抑止します。

-f reffile
    相互参照ファイルの名前として、 デフォルトの cscope.out の代わりに reffile を使用します。

-Iincdir
    #include ファイルの名前が / で始まっておらず、 コマンド行にも下記の namefile にも指定されていない場合に、 ヘッダファイルの標準の格納場所である INCDIR (通常は /usr/include) で探す前に、 incdir で探します ( #include ファイルは二重引用符と山括弧のどちらでも指定できます)。 #include ファイルは、現作業ディレクトリ、 incdir で指定したディレクトリ、 標準の格納場所の順に検索されます。 複数の -I オプションを指定した場合は、 コマンド行で最初に現れたディレクトリから順に検索されます。

-inamefile
    デフォルトのファイル ( cscope.files ) の代わりに、 namefile に指定した名前のソースファイルを検査します ( namefile に 複数のファイル名を指定する場合は、それぞれをスペース、タブ、 または復帰改行 (NEWLINE) で区切ってください)。 このオプションを指定すると、 コマンド行引数として指定したすべてのファイルが無視されます。

-L  -num pattern オプションとともに使用し、 1 回の検索を行なって、その結果を 1 行に表示します。

-l  行処理向きインタフェース (後述の「行処理向きインタフェース」を参照)。

-num pattern
    入力フィールド num (0 からカウントする) に進み、 pattern を検索します。

-Ppath
    相互参照ファイル (作成済みのもの) に現れる相対パス名の 前に path を付けます。 これにより、その相互参照を作成したディレクトリに 移動しなくてもすむようにします。 このオプションは、 -d オプションを使用した場合にだけ有効です。

-pn ファイルパスの後ろから n 個の構成要素を表示します。 デフォルト値は 1 で、パス名の最後の構成要素だけが表示されます。 ファイル名をまったく出力しない場合は 0 を使用してください。

-sdir
    追加のソースファイルを dir で探します。 コマンド行引数としてソースファイルを指定した場合、 このオプションは無視されます。

-T  C のシンボルと照合するときに先頭の 8 文字だけを使用します。 ピリオド (.) 以外の特殊文字を含む正規表現は、 その最短の長さが 8 文字より長いときにはどのシンボルとも一致しません。

-U  ファイルの日付をチェックしません (どのファイルにも 変更がないと見なします)。

-u  相互参照ファイルを無条件に作成します (すべての ファイルが変更されたものと見なします)。

-V  画面の先頭の行に cscope のバージョン番号を表示します。

-I 、 -p 、 -T の各オプションは、ファイル cscope.files の中にも置くことができます。

  初期検索の要求
相互参照の準備が完了すると、 cscope は次のメニューを表示します。

    Find this C symbol:
    Find this global definition:
    Find functions called by this function:
    Find functions calling this function:
    Find this text string:
    Change this text string:
    Find this egrep pattern:
    Find this file:
    Find files #including this file:

Tab キーを繰り返し押して希望する入力フィールドに移動し、 検索テキストを入力して Return キーを押してください。

  検索後の要求
検索が正常に行われると、 次のいずれかの文字を使用できます。

1-9 該当する行番号によって参照されるファイルを編集します。
スペース
    一致する次の行を表示します。
+   一致する次の行を表示します。
-   一致する前の行を表示します。
^e  表示されたファイルを順番に編集します。
>   表示された行の並びをファイルに追加します。
|   パイプを介し、すべての行をシェルコマンドに渡します。

次のコマンドはいつでも使用することができます。

Tab 次の入力フィールドに移動します。
RETURN
    次の入力フィールドに移動します。
^n  次の入力フィールドに移動します。
^p  1 つ前の入力フィールドに移動します。
^y  最後に入力したテキストを検索します。
^b  1 つ前の入力フィールドに移動し、パターンを検索します。
^f  次の入力フィールドに移動し、パターンを検索します。
^c  検索時に大文字 / 小文字を無視するか区別するかを切り替えます (大文字 / 小文字を 無視する場合、 FILE の検索時には File と file も一致します)。
^r  相互参照を再作成します。
!   対話型シェルを起動します ( cscope に戻るには、^d と入力します)。
^l  画面を再表示します。
?   cscope の各コマンドについてのヘルプ情報を表示します。
^d  cscope を終了します。

注意 : 検索対象のテキストの最初の文字が上記のコマンドのいずれかに 一致するときは、その前で \ (バックスラッシュ) をタイプして エスケープしてください。

  テキストの置換
変更対象のテキストを入力すると、 新しいテキストを入力するように求められ、 古いテキストを含む行が表示されます。 次のコマンドを使って、変更する行を選んでください。

1-9 特定の行を変更対象の行としてマークまたはマーク解除します。
*   表示されたすべての行を変更対象の行としてマークまたは マーク解除します。
スペース
    次の行を表示します。
+   次の行を表示します。
-   1 つ前の行を表示します。
a   すべての行を変更対象としてマークします。
^d  マークした行を変更して終了します。
Esc マークした行を変更しないで終了します。
!   対話型シェルを起動します ( cscope に戻るには、^d と入力します)。
^l  画面を再表示します。
?   cscope の各コマンドについてのヘルプ情報を表示します。

  特殊キー
使用する端末に vi(1) 上で機能する矢印キーがある場合は、 それらを使って入力フィールドの間を移動することができます。 たとえば、1 つ前の入力フィールドに移動するために Tab キーを繰り返し押すよりも、上向き矢印キーを使うと便利です。 Clear (クリア) キー、 Next (次) キー、 Prev (前) キーがあれば、それぞれが コマンド ^l、+、- として機能します。

  行処理用インタフェース
-l オプションを指定すると、 画面処理用インタフェースが使用できない場合 (別の画面処理用プログラムから 使用する場合など) でも、 cscope を使用できます。
cscope は、フィールド番号 (0 から開始) から始まり、 直後に検索パターンが続く入力行の準備ができると、 プロンプト >> を表示します。 たとえば、 lmain とすると、 main 関数の定義が検索されます。
検索を 1 回だけ行いたい場合は、 -l オプションの代わりに、 -L オプションと -num pattern を使用してください。 その場合、>> プロンプトは表示されません。
-l の場合、 cscope は参照行の数を出力します。

    cscope: 2 lines

参照箇所を見つけるたびに、 cscope はそのファイル名、関数名、行番号、その行のテキストを スペースで区切って、1 行に表示します。 たとえば、次のように出力します。

    main.c main 161 main(argc, argv)
画面処理用インタフェースとは異なり、 単一の参照箇所を表示するためにエディタが呼び出されることはありません。
r コマンドを使用すれば、データベースを再構築できます。
ファイルの終端を検出するか、行の先頭で ^d または q が 入力されると cscope は終了します。

環境変数

EDITOR
    使用するエディタ。デフォルトでは vi(1) が使用されます。
INCLUDEDIRS
    #include ファイルを検索するディレクトリのコロンで区切った並び。
HOME
    ホームディレクトリ。 ログイン時に自動的に設定されます。
SHELL
    使用するシェル。デフォルトでは sh(1) に設定されます。
SOURCEDIRS
    追加のソースファイルを検索するディレクトリのコロンで区切った並び。
TERM
    端末タイプ。画面ターミナルでなければなりません。
TERMINFO
    端末情報が入ったディレクトリのフルパス名。 使用中の端末が標準のディレクトリ terminfo にない場合は、 curses(3X) および terminfo(4) を参照して、独自の端末記述を作成してください。
TMPDIR
    一時ファイル用ディレクトリ。 デフォルトでは、/var/tmp に設定されます。
VIEWER
    使用するファイル表示プログラム ( pg など)。この変数の値は、 EDITOR
     (上記) の値に優先して使用されます。
VPATH
    コロンで区切ったディレクトリの並び。 各ディレクトリは、下位に同じディレクトリ構造を持っています。 VPATH が設定されていると、 cscope は指定されたディレクトリでソースファイルを検索します。 この変数が設定されていない場合、 cscope は現作業ディレクトリだけで検索を行います。

ファイル

cscope.files
    オプション -I 、 -p 、 -T と、ソースファイルの並び ( -i オプションによって上書きされる) が入っている デフォルトファイル。

cscope.out
    シンボルの相互参照ファイル。 現作業ディレクトリに作成できない場合は、 ホームディレクトリに作成されます。

ncscope.out
    新しい相互参照を古い 相互参照に上書きする前の一時ファイル。

関連項目
『C ユーザーズガイド』

注意事項
cscope は、次の形式の関数定義を認識します。

    fname blank ( args ) white arg_decs white {

fname
    関数名

blank
    ゼロ個以上のスペースまたはタブ (復帰改行は含まない)

args
    " および復帰改行を含まない任意の文字列

white
    ゼロ個以上のスペース、タブ、または復帰改行

arg_decs
    ゼロ個以上の引数宣言 ( arg_decs にはコメントや空白類を含むことができる)

関数の宣言は、行の先頭から始める必要はありません。 関数名の前には、戻り型を置くことができます。 その場合でも、 cscope は宣言を認識します。 これ以外の形式の関数定義は認識しません。

メニューオプション Find functions called by this function: による 検索結果の出力の Function 欄には、行で呼び出された最初の関数だけが 表示されます。たとえば、

    e()
    {
    	return (f() + g());
    }

この場合、結果の出力は次のとおりです。

    Functions called by this function: e
    File Function Line
    a.c  f	3 return(f() + g());

#if 文の内部に中括弧 {} があると、 関数定義または関数呼び出しが認識されないことがあります。 同様に、変数が定義として、誤って認識されることがあります。

次のように、 typedef で定義された名前が前処理文の前にあると、 それが大域定義として誤って解釈されることがあります。

    LDFILE *
    #if AR16WR

また、次のような前処理文により、 大域定義が認識されないことがあります。

    char flag
    #ifdef ALLOCATE_STORAGE
    	= -1
    #endif
    ;

関数内部の関数定義は、関数呼び出しと誤って認識されます。 たとえば、

    f()
    {
    	void g();
    }
これは、g() の呼び出しと認識されます。

cscope は、キーワード class を検索することで C++ のクラスを認識します。しかし、 struct もクラスであるとは認識しません。 したがって、構造体内部のインライン・メンバーの関数定義を認識しません。 さらに、 typedef 内にキーワード class を想定していないため、次のような場合の X は誤って定義として認識されます。

    typedef class X * Y;

次のような演算子関数の定義は認識しません。

    Bool Feature::operator==(const Feature & other)
    {
    	...
    }