|C User's Guide|
The cscope Process Basic Use Unknown Terminal Type Error
cscopeis an interactive program that locates specified elements of code in C,
yaccsource files. With
cscope, you can search and edit your source files more efficiently than you could with a typical editor. That's because
cscopesupports function calls--when a function is being called, when it is doing the calling--as well as C language identifiers and keywords.
cscopeis called for a set of C,
yaccsource 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. First, it presents a menu and asks you to choose the type of search you would like to have performed. You may, for instance, want
cscopeto find all the functions that call a specified function.
cscopehas completed this search, it 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
cscopehas found the specified code. In our case, the list also includes the names of the functions that call the specified function. You now have the option of requesting another search or examining one of the listed lines with the editor. If you choose the latter,
cscopeinvokes the editor for the file in which the line appears, with the cursor on that line. You can now view the code in context and, if you wish, edit the file as any other file. You can then return to the menu from the editor to request a new search.
Because the procedure you follow depends on the task at hand, there is no single set of instructions for using
cscope. For an extended example of its use, review the
cscopesession described in the next section. It shows how you can locate a bug in a program without learning all the code.
Suppose you are given responsibility for maintaining the program
prog. You are told that an error message, out of storage, sometimes appears just as the program starts up. Now you want to use
cscopeto locate the parts of the code that are generating the message. Here is how you do it.
cscopeis a screen-oriented tool that can only be used on terminals listed in the Terminal Information Utilities (
terminfo) database. Be sure you have set the
TERMenvironment variable to your terminal type so that
cscopecan verify that it is listed in the
terminfodatabase. If you have not done so, assign a value to
TERMand export it to the shell as follows:
You may now want to assign a value to the
EDITORenvironment variable. By default,
vieditor. (The examples in this chapter illustrate
viusage.) If you prefer not to use
vi, set the
EDITORenvironment variable to the editor of your choice and export
EDITOR, as follows:
EDITOR=emacs; export EDITOR
setenv EDITOR emacs
You may have to write an interface between
cscopeand your editor. For details, see Command-Line Syntax for Editors.
An environment variable called
VPATHcan be set to specify directories to be searched for source files. See View Paths.
cscopebuilds a symbol cross-reference table for all the C,
yaccsource 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
For other ways to invoke
cscope, see Command-Line Options.
cscopebuilds 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.outin the current directory. On a subsequent invocation,
cscoperebuilds the cross-reference only if a source file has been modified or the list of source files is different. When the cross-reference is rebuilt, the data for the unchanged files is copied from the old cross-reference, which makes rebuilding faster than the initial build, and reduces startup time for subsequent invocations.
Now let's return to the task we undertook at the beginning of this section: to identify the problem that is causing the error message out of storage to be printed. You have invoked
cscope, the cross-reference table has been built. The
cscopemenu of tasks appears on the screen.
Press the Return key to move the cursor down the screen (with wraparound at the bottom of the display), and
^p(Control-p) to move the cursor up; or use the up (
ua) and down (
da) arrow keys. You can manipulate the menu and perform other tasks with the following single-key commands:
out of storage
Note – Follow the same procedure to perform any other task listed in the menu except the sixth,
string. Because this task is slightly more complex than the others, there is a different procedure for performing it. For a description of how to change a text string, see Examples.
cscopeshows 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
cscopehas 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. The following table shows the commands available after
cscopehas found the specified text:
You can see that the error message is generated when the variable
NULL. To determine how an argument passed to
alloctest()could have been
NULL, you must first identify the functions that call
Because you know that the error message out of storage is generated at the beginning of the program, you can guess that the problem may have occurred in the function
mymalloc()failed because it was called either with a very large number or a negative number. By examining the possible values of
REFLINE, you can see that there are situations in which the value of
mdisprefsis negative, that is, in which you are trying to call
mymalloc()with a negative number.
On a windowing terminal, you may have multiple windows of arbitrary size. The error message out of storage might have appeared as a result of running
progin a window with too few lines. In other words, that may have been one of the situations in which
mymalloc()was called with a negative number. Now you want to be sure that when the program aborts in this situation in the future, it does so after printing the more meaningful error message screen too small. Edit the function
You have fixed the problem we began investigating at the beginning of this section. Now if
progis run in a window with too few lines, it does not simply fail with the unedifying error message out of storage. Instead, it checks the window size and generates a more meaningful error message before exiting.
cscopeprovides command-line options with greater flexibility in specifying source files to be included in the cross-reference. When you invoke
-soption and any number of directory names (separated by commas):
cscopebuilds a cross-reference for all the source files in the specified directories as well as the current directory. To browse through all of the source files whose names are listed in file (file names separated by spaces, tabs, or new-lines), invoke
-ioption and the name of the file containing the list:
find . -name '*.[chly]' -print | sort >file
-Ioption can be used for
cscopein the same way as the
cc. See Include Files.
You can specify a cross-reference file other than the default
cscope.outby invoking the
-foption. This is useful for keeping separate symbol cross-reference files in the same directory. You may want to do this if two programs are in the same directory, but do not share all the same files:
cscope -f admin.ref admin.c common.c aux.c libs.c
cscope -f delta.ref delta.c common.c aux.c libs.c
In this example, the source files for two programs,
delta, are in the same directory, but the programs consist of different groups of files. By specifying different symbol cross-reference files when you invoke
cscopefor each set of source files, the cross-reference information for the two programs is kept separate.
You can use the
-pn option to specify that
cscopedisplay the path name, or part of the path name, of a file when it lists the results of a search. The number you give to
-pstands for the last n elements of the path name you want to be displayed. The default is
1, the name of the file itself. So if your current directory is
home/common, the command:
If the program you want to browse contains a large number of source files, you can use the
-boption, so that
cscopestops after it has built a cross-reference;
cscopedoes not display a menu of tasks. When you use
cscope -bin a pipeline with the
cscopebuilds the cross-reference in the background:
echo 'cscope -b' | batch
for the cross-reference to be copied and the menu of tasks to be displayed in the normal way. You can use this sequence of commands when you want to continue working without having to wait for
cscopeto finish its initial processing.
cscopenot to update the symbol cross-reference. You can use it to save time if you are sure that no such changes have been made;
cscopedoes not check the source files for changes.
Note – Use the
-doption with care. If you specify
-dunder the erroneous impression that your source files have not been changed,
cscoperefers to an outdated symbol cross-reference in responding to your queries.
As we have seen,
cscopesearches for source files in the current directory by default. When the environment variable
cscopesearches for source files in directories that comprise your view path. A view path is an ordered list of directories, each of which has the same directory structure below it.
For example, suppose you are part of a software project. There is an official set of source files in directories below
/fs1/ofc. Each user has a home directory (
/usr/you). If you make changes to the software system, you may have copies of just those files you are changing in
/usr/you/src/cmd/prog1. The official versions of the entire program can be found in the directory
VPATH=/usr/you:/fs1/ofc; export VPATH
setenv VPATH /usr/you:/fs1/ofc
The program locates all the files in the view path. In case duplicates are found,
cscopeuses the file whose parent directory appears earlier in
VPATH. Thus, if
f2.cis in your directory, and all three files are in the official directory,
f2.cfrom your directory, and
f3.cfrom the official directory.
cscopeand editor calls can be stacked. That is, when
cscopeputs you in the editor to view a reference to a symbol and there is another reference of interest, you can invoke
cscopeagain from within the editor to view the second reference without exiting the current invocation of either
cscopeor the editor. You can then back up by exiting the most recent invocation with the appropriate
cscopeand editor commands.
This section presents examples of how
cscopecan be used to perform three tasks: changing a constant to a preprocessor symbol, adding an argument to a function, and changing the value of a variable. The first example demonstrates the procedure for changing a text string, which differs slightly from the other tasks on the
cscopemenu. That is, once you have entered the text string to be changed,
cscopeprompts you for the new text, displays the lines containing the old text, and waits for you to specify which of these lines you want it to change.
Suppose you want to change a constant,
100, to a preprocessor symbol,
MAXSIZE. Select the sixth menu item,
string, and enter
1must be escaped with a backslash because it has a special meaning (item 1 on the menu) to
cscope. Now press Return.
cscopeprompts you for the new text string. Type
You know that the constant
100in lines 1, 2, and 3 of the list (lines 4, 26, and 8 of the listed source files) should be changed to
MAXSIZE. You also know that
err.c(lines 4 and 5 of the list) should not be changed. You select the lines you want changed with the following single-key commands:
In this case, enter
The numbers you type are not printed on the screen. Instead,
cscopemarks each list item you want to be changed by printing a
>(greater than) symbol after its line number in the list.
The next step is to add the
#definefor the new symbol
MAXSIZE. Because the header file in which the
#defineis to appear is not among the files whose lines are displayed, you must escape to the shell by typing
!. The shell prompt appears at the bottom of the screen. Then enter the editor and add the
First, edit the function by using the second menu item,
global definition. Next, find out where the function is called. Use the fourth menu item,
function, to obtain a list of all the functions that call it. With this list, you can either invoke the editor for each line found by entering the list number of the line individually, or invoke the editor for all the lines automatically by typing
cscopeto make this kind of change ensures that none of the functions you need to edit are overlooked.
Suppose you want to change the value of a variable or preprocessor symbol. Before doing so, use the first menu item,
symbol, to obtain a list of references that are affected. Then use the editor to examine each one. This step helps you predict the overall effects of your proposed change. Later, you can use
cscopein the same way to verify that your changes have been made.
vieditor by default. You can override the default setting by assigning your preferred editor to the
EDITORenvironment variable and exporting
EDITOR, as described in Step 1: Set Up the Environment. However,
cscopeexpects the editor it uses to have a command-line syntax of the form:
Suppose you want to use
eddoes not allow specification of a line number on the command-line, you cannot use it to view or edit files with
cscopeunless you write a shell script that contains the following line:
EDITOR=myedit; export EDITOR
setenv EDITOR myedit
myeditthen discards the line number (
$1) and calls
edcorrectly with the file name (
$2). Of course, you are not moved automatically to line 17 of the file and must execute the appropriate
edcommands to display and edit the line.
your terminal may not be listed in the Terminal Information Utilities (
terminfo) database that is currently loaded. Make sure you have assigned the correct value to
TERM. If the message reappears, try reloading the Terminal Information Utilities.
set and export the
TERMvariable as described in Step 1: Set Up the Environment.
|Sun Microsystems, Inc.
Copyright information. All rights reserved.
|Library | Contents | Previous | Next | Index|