8.2.8 Examples

This section presents examples of how cscope can 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 cscope menu. That is, once you have entered the text string to be changed, cscope prompts 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.

8.2.8.1 Changing a Constant to a Preprocessor Symbol

Suppose you want to change a constant, 100, to a preprocessor symbol, MAXSIZE. Select the sixth menu item, Change this text string, and enter \100. The 1 must be escaped with a backslash because it has a special meaning (item 1 on the menu) to cscope. Now press Return. cscope prompts you for the new text string. Type MAXSIZE.

cscope Function: Changing a Text String:

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: \100
Find this egrep pattern:
Find this file:
Find files #including this file:
To:  MAXSIZE

cscope displays the lines containing the specified text string, and waits for you to select those in which you want the text to be changed.

cscope Function: Prompting for Lines to be Changed:

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: \100
Find this egrep pattern:
Find this file:
Find files #including this file:
To:  MAXSIZE

You know that the constant 100 in 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 0100 in read.c and 100.0 in 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 1, 2, and 3. The numbers you type are not printed on the screen. Instead, cscope marks each list item you want to be changed by printing a > (greater than) symbol after its line number in the list.

cscope Function: Marking Lines to be Changed:

Change "100" to "MAXSIZE"

  File Line
1>init.c 4 char s[100];
2>init.c 26 for (i = 0; i < 100; i++)
3>find.c 8 if (c < 100) {
4 read.c 12 f = (bb & 0100);
5 err.c 19 p = total/100.0; /* get percentage */

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:
Select lines to change (press the ? key for help):

Now type ^d to change the selected lines. cscope displays the lines that have been changed and prompts you to continue.

cscope Function: Displaying Changed Lines of Text:

Changed lines:

    char s[MAXSIZE];
    for (i = 0; i < MAXSIZE; i++)
    if (c < MAXSIZE) {

Press the RETURN key to continue:

When you press Return in response to this prompt, cscope redraws the screen, restoring it to its state before you selected the lines to be changed.

The next step is to add the #define for the new symbol MAXSIZE. Because the header file in which the #define is 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 #define.

cscope Function: Exiting to the Shell:

Text string: 100

  File Line
1 init.c 4 char s[100];
2 init.c 26 for (i = 0; i < 100; i++)
3 find.c 8 if (c < 100) {
4 read.c 12 f = (bb & 0100);
5 err.c 19 p = total/100.0;                                        /* get percentage */

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:
$ vi defs.h

To resume the cscope session, quit the editor and type ^d to exit the shell.

8.2.8.2 Adding an Argument to a Function

Adding an argument to a function involves two steps: editing the function itself and adding the new argument to every place in the code where the function is called.

First, edit the function by using the second menu item, Find this global definition. Next, find out where the function is called. Use the fourth menu item, Find functions calling this 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 ^e. Using cscope to make this kind of change ensures that none of the functions you need to edit are overlooked.

8.2.8.3 Changing the Value of a Variable

At times, you may want to see how a proposed change affects your code.

Suppose you want to change the value of a variable or preprocessor symbol. Before doing so, use the first menu item, Find this C 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 cscope in the same way to verify that your changes have been made.