UNIX/C: cscope - an interactive program examiner

cscope is an interactive program that locates specified elements of code in C,

C++, lex, or yacc source files. cscope  is a very useful utility to browse through

the source code tree of a large project. It is a text-mode screen-oriented utility.



When cscope is called for a set of C, C++, lex, or yacc source files, it builds a

symbol cross-reference table for the functions, function calls, macros, variables,

and preprocessor symbols in those files. You can then query that table about the

locations of symbols you specify.



At First, cscope presents a menu and asks you to choose the type of search you

would like to  perform. You may, for instance, want cscope to find all the

functions that call a specified function. When it completes the search, cscope

prints a list.  Each list entry contains the name of the file, the number of the line,

and the text of the line in which cscope has found the specified code. In our case,

the list also includes the names of the functions that call the specified function.

We now have the option of requesting another search or examining one of the

listed lines with the editor. If we choose the latter, cscope invokes the editor (vi)

for the file in which the line appears, with the cursor on that line. We can now

view the code in context and, if we wish, edit the file as any other file. By simply

using vi editor's edit keys we can either navigate through the code or return back

to the menu to request a new search.



Lets try building symbol cross-reference table & search for some symbols using

cscope



bpte4500s001:/sunbuild1/giri/testcases/cscope/%ls

hidden.cpp    hidden.h      hide.cpp      htest.cpp     test.h

testcase.cpp  x.cpp         x.h



bpte4500s001:/sunbuild1/giri/testcases/cscope/%which cscope

/home/sundev/S1S9/SUNWspro/bin/cscope

^^^^

cscope is part of Sun Studio Compiler Collection 



By default, cscope builds a symbol cross-reference table for all the C, C++, lex,

and yacc source files in the current directory, and for any included header files in

the current directory or the standard place. So, if all the source files for the

program to be browsed are in the current directory, and if its header files are

there or in the standard place, invoke cscope without arguments



bpte4500s001:/sunbuild1/giri/testcases/cscope/%cscope

---------------------------------------------------------------------

cscope                                       Press the ? key for help









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:

---------------------------------------------------------------------



cscope builds the symbol cross-reference table the first time it is used on the

source files for the program to be browsed. By default, the table is stored in the

file "cscope.out" in the current directory. On a subsequent invocation, cscope

rebuilds the cross-reference only if a source file has been modified or the list of

source files is different



bpte4500s001:/sunbuild1/giri/testcases/cscope/%ls

cscope.out    hidden.cpp    hidden.h      hide.cpp

htest.cpp     test.h        testcase.cpp  x.cpp         x.h



bpte4500s001:/sunbuild1/giri/testcases/cscope/%file cscope.out

cscope.out:     data



bpte4500s001:/sunbuild1/giri/testcases/cscope/%cat hidden.h

__declspec(dllexport) char *lastname(char *);

//char *lastname(char *);

__declspec(dllexport)

int agefunc();

__declspec(dllexport)

char firstchar(char *);



Now lets try to locate the function "lastname" using cscope



---------------------------------------------------------------------

C symbol: lastname



File     Function   Line

1 hidden.h __declspec 1 __declspec(dllexport) char *lastname(char *);







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:

---------------------------------------------------------------------



After cscope shows you the results of a successful search, you have several

options. You may want to change one of the lines or examine the code

surrounding it in the editor. Or, if cscope has found so many lines that a list of

them does not fit on the screen at once, you may want to look at the next part of

the list.



If you want to open up "hidden.h", just press 1; it opens up "hidden.h" in vi

editor. If more than one file has the designated symbol, we just need to press

the number that is besides the file name which we want to edit. If the search

yields more results and if all the results doesn't fit in a single screen, we need

to press "space bar" to go to the next screen. To go back to the previous screen,

we need to press "--"



NOTE:

If the source code of a project is spread over different directories we need to get

the list of files (with the path) and save the list in a file called "cscope.files".

Then run cscope to build the symbol cross-reference table & to show the menu.

Once the symbol cross-reference table is ready & if there are no changes in the

source code, invoke cscope with "-d" flag from subsequent executions. "-d"

instructs cscope not to update the cross-reference



bpte4500s001:/sunbuild1/giri/testcases/cscope/%ls -ld *

drwxrwxr-x   2 build    engr         512 Nov 15 16:44 hidden

-rw-r--r--   1 build    engr          79 Nov 15 16:18 htest.cpp

drwxrwxr-x   2 build    engr         512 Nov 15 16:44 test

drwxrwxr-x   2 build    engr         512 Nov 15 16:44 x



bpte4500s001:/sunbuild1/giri/testcases/cscope/%ls -lR *

-rw-r--r--   1 build    engr          79 Nov 15 16:18 htest.cpp



hidden:

total 6

-rw-r--r--   1 build    engr         320 Nov 15 16:18 hidden.cpp

-rw-r--r--   1 build    engr         155 Nov 15 16:18 hidden.h

-rw-r--r--   1 build    engr         358 Nov 15 16:18 hide.cpp



test:

total 4

-rw-rw-r--   1 build    engr          42 Nov 15 16:18 test.h

-rw-rw-r--   1 build    engr         354 Nov 15 16:18 testcase.cpp



x:

total 4

-rw-r--r--   1 build    engr          60 Nov 15 16:18 x.cpp

-rw-r--r--   1 build    engr          47 Nov 15 16:18 x.h



bpte4500s001:/sunbuild1/giri/testcases/cscope/%cscope

cscope: no source files found



bpte4500s001:/sunbuild1/giri/testcases/cscope/%find . -name "*" > cscope.files



bpte4500s001:/sunbuild1/giri/testcases/cscope/%ls

cscope.files  hidden        htest.cpp     test          x



bpte4500s001:/sunbuild1/giri/testcases/cscope/%cscope

(.. skipped cscope menu ..)



bpte4500s001:/sunbuild1/giri/testcases/cscope/%ls

cscope.files  hidden        test

cscope.out    htest.cpp     x



Note:

If cscope throws an error message like "Input string too long, limit 50251",

run truss on cscope and observe the last few lines to find the culprit and remove

it from cscope.files to let cscope continue building the symbol database



Courtesy:

Sun Microsystems, Sun Studio 9: C User's Guide