1CSCOPE(1)                   General Commands Manual                  CSCOPE(1)
2
3
4

NAME

6       cscope - interactively examine a C program
7

SYNOPSIS

9       cscope  [-bCcdehkLlqRTUuVv] [-Fsymfile] [-freffile] [-Iincdir] [-iname‐
10       file] [-[0123456789]pattern] [-pn] [-sdir] [files]
11

DESCRIPTION

13       cscope is an interactive, screen-oriented tool that allows the user  to
14       browse through C source files for specified elements of code.
15
16       By  default, cscope examines the C (.c and .h), lex (.l), and yacc (.y)
17       source files in the current directory.  cscope may also be invoked  for
18       source files named on the command line. In either case, cscope searches
19       the standard directories for #include files that it does  not  find  in
20       the  current  directory.   cscope uses a symbol cross-reference, called
21       cscope.out by default, to locate  functions,  function  calls,  macros,
22       variables, and preprocessor symbols in the files.
23
24       cscope  builds  the symbol cross-reference the first time it is used on
25       the source files for the program being browsed. On a subsequent invoca‐
26       tion,  cscope  rebuilds  the  cross-reference only if a source file has
27       changed or the list of source files is different. When the cross-refer‐
28       ence  is  rebuilt, the data for the unchanged files are copied from the
29       old cross-reference, which makes rebuilding  faster  than  the  initial
30       build.
31

OPTIONS

33       Some  command  line arguments can only occur as the the ony argument in
34       the execution of cscope.  They cause the program to just print out some
35       output and exit immediately:
36
37       -h     View the long usage help display.
38
39       -V     Print on the first line of screen the version number of cscope.
40
41       --help Same as -h
42
43       --version
44              Same as -V
45
46
47       The following options can appear in any combination:
48
49       -b     Build the cross-reference only.
50
51       -C     Ignore letter case when searching.
52
53       -c     Use  only ASCII characters in the cross-reference file, that is,
54              do not compress the data.
55
56       -d     Do not update the cross-reference.
57
58       -e     Suppress the <Ctrl>-e command prompt between files.
59
60       -Fsymfile
61              Read symbol reference lines from symfile.  (A  symbol  reference
62              file  is  created  by > and >>, and can also be read using the <
63              command,  described  under  ``Issuing   Subsequent   Requests,''
64              below.)
65
66       -freffile
67              Use  reffile  as  the  cross-reference  file name instead of the
68              default "cscope.out".
69
70       -Iincdir
71              Look in incdir (before looking in $INCDIR,  the  standard  place
72              for  header files, normally /usr/include) for any #include files
73              whose names do not begin with ``/'' and that are  not  specified
74              on  the  command  line or in namefile below. (The #include files
75              may be specified with either double quotes or  angle  brackets.)
76              The  incdir  directory  is  searched  in addition to the current
77              directory (which is searched first) and the standard list (which
78              is  searched  last).  If more than one occurrence of -I appears,
79              the directories are searched in the order  they  appear  on  the
80              command line.
81
82       -inamefile
83              Browse  through all source files whose names are listed in name‐
84              file (file  names  separated  by  spaces,  tabs,  or  new-lines)
85              instead   of  the  default  name  list  file,  which  is  called
86              cscope.files. If this option is specified,  cscope  ignores  any
87              file  names appearing on the command line. The argument namefile
88              can be set to ``-'' to accept a list of files from the  standard
89              input.   Filenames  in the namefile that contain whitespace have
90              to be enclosed in "double quotes".   Inside  such  quoted  file‐
91              names,  any  double-quote  and  backslash  characters have to be
92              escaped by backslashes.
93
94       -k     ``Kernel Mode'', turns off the use of the  default  include  dir
95              (usually  /usr/include) when building the database, since kernel
96              source trees generally do not use it.
97
98       -L     Do a single search with line-oriented output when used with  the
99              -num pattern option.
100
101       -l     Line-oriented interface (see ``Line-Oriented Interface'' below).
102
103       -[0-9]pattern
104              Go to input field num (counting from 0) and find pattern.
105
106       -Ppath Prepend  path to relative file names in a pre-built cross-refer‐
107              ence file so you do not have to change to  the  directory  where
108              the  cross-reference  file  was built. This option is only valid
109              with the -d option.
110
111       -pn    Display the last n file path components instead of  the  default
112              (1). Use 0 to not display the file name at all.
113
114       -q     Enable  fast  symbol  lookup  via an inverted index. This option
115              causes  cscope  to  create   2   more   files   (default   names
116              ``cscope.in.out'' and ``cscope.po.out'') in addition to the nor‐
117              mal database. This allows a faster symbol search algorithm  that
118              provides   noticeably   faster   lookup  performance  for  large
119              projects.
120
121       -R     Recurse subdirectories during search for source files.
122
123       -sdir  Look in dir for additional source files. This option is  ignored
124              if source files are given on the command line.
125
126       -T     Use  only the first eight characters to match against C symbols.
127              A regular expression containing special characters other than  a
128              period  (.)  will  not match any symbol if its minimum length is
129              greater than eight characters.
130
131       -U     Check file time stamps. This option will update the  time  stamp
132              on the database even if no files have changed.
133
134       -u     Unconditionally  build the cross-reference file (assume that all
135              files have changed).
136
137       -v     Be more verbose in line-oriented mode.  Output progress  updates
138              during database building and searches.
139
140       files  A list of file names to operate on.
141
142       The  -I, -c, -k, -p, -q, and -T options can also be in the cscope.files
143       file.
144
145       Requesting the initial search
146
147       After the cross-reference is ready, cscope will display this menu:
148
149       Find this C symbol:
150       Find this function definition:
151       Find functions called by this function:
152       Find functions calling this function:
153       Find this text string:
154       Change this text string:
155       Find this egrep pattern:
156       Find this file:
157       Find files #including this file:
158
159       Press the <Up> or <Down> keys repeatedly to move to the  desired  input
160       field, type the text to search for, and then press the <Return> key.
161

Issuing subsequent requests

163       If the search is successful, any of these single-character commands can
164       be used:
165
166       0-9a-zA-Z
167              Edit the file referenced by the given line number.
168
169       <Space>
170              Display next set of matching lines.
171
172       <Tab>  Alternate between the menu and the list of matching lines
173
174       <Up>   Move to the previous menu item (if the cursor is in the menu) or
175              move  to  the  previous  matching  line (if the cursor is in the
176              matching line list.)
177
178       <Down> Move to the next menu item (if the cursor is  in  the  menu)  or
179              move to the next matching line (if the cursor is in the matching
180              line list.)
181
182       +      Display next set of matching lines.
183
184       -      Display previous set of matching lines.
185
186       ^e     Edit displayed files in order.
187
188       >      Write the displayed list of lines to a file.
189
190       >>     Append the displayed list of lines to a file.
191
192       <      Read lines from a file that is in symbol reference format  (cre‐
193              ated by > or >>), just like the -F option.
194
195       ^      Filter all lines through a shell command and display the result‐
196              ing lines, replacing the lines that were already there.
197
198       |      Pipe all lines to a  shell  command  and  display  them  without
199              changing them.
200
201       At any time these single-character commands can also be used:
202
203       <Return>
204              Move to next input field.
205
206       ^n     Move to next input field.
207
208       ^p     Move to previous input field.
209
210       ^y     Search with the last text typed.
211
212       ^b     Move to previous input field and search pattern.
213
214       ^f     Move to next input field and search pattern.
215
216       ^c     Toggle  ignore/use  letter  case  when searching. (When ignoring
217              letter  case,  search  for  ``FILE''  will  match  ``File''  and
218              ``file''.)
219
220       ^r     Rebuild the cross-reference.
221
222       !      Start an interactive shell (type ^d to return to cscope).
223
224       ^l     Redraw the screen.
225
226       ?      Give help information about cscope commands.
227
228       ^d     Exit cscope.
229
230       NOTE: If the first character of the text to be searched for matches one
231       of the above commands, escape it by typing a (backslash) first.
232
233       Substituting new text for old text
234
235       After the text to be changed has been typed, cscope will prompt for the
236       new  text,  and then it will display the lines containing the old text.
237       Select the lines to be changed with these single-character commands:
238
239       0-9a-zA-Z
240              Mark or unmark the line to be changed.
241
242       *      Mark or unmark all displayed lines to be changed.
243
244       <Space>
245              Display next set of lines.
246
247       +      Display next set of lines.
248
249       -      Display previous set of lines.
250
251       a      Mark or unmark all lines to be changed.
252
253       ^d     Change the marked lines and exit.
254
255       <Esc>  Exit without changing the marked lines.
256
257       !      Start an interactive shell (type ^d to return to cscope).
258
259       ^l     Redraw the screen.
260
261       ?      Give help information about cscope commands.
262
263       Special keys
264
265       If your terminal has arrow keys that work in vi, you can  use  them  to
266       move around the input fields. The up-arrow key is useful to move to the
267       previous input field instead of using the <Tab> key repeatedly. If  you
268       have  <CLEAR>, <NEXT>, or <PREV> keys they will act as the ^l, +, and -
269       commands, respectively.
270
271       Line-Oriented interface
272
273       The -l option lets you use cscope  where  a  screen-oriented  interface
274       would not be useful, for example, from another screen-oriented program.
275
276       cscope  will prompt with >> when it is ready for an input line starting
277       with the field number (counting from 0)  immediately  followed  by  the
278       search pattern, for example, ``lmain'' finds the definition of the main
279       function.
280
281       If you just want a single search, instead of the -l option use  the  -L
282       and -num pattern options, and you won't get the >> prompt.
283
284       For -l, cscope outputs the number of reference lines cscope: 2 lines
285
286       For  each reference found, cscope outputs a line consisting of the file
287       name, function name, line number, and line text, separated  by  spaces,
288       for example, main.c main 161 main(argc, argv)
289
290       Note  that  the  editor  is  not  called to display a single reference,
291       unlike the screen-oriented interface.
292
293       You can use the c command to toggle ignore/use letter case when search‐
294       ing.  (When  ignoring  letter  case,  search  for  ``FILE''  will match
295       ``File'' and ``file''.)
296
297       You can use the r command to rebuild the database.
298
299       cscope will quit when it detects end-of-file, or when the first charac‐
300       ter of an input line is ``^d'' or ``q''.
301

ENVIRONMENT VARIABLES

303       CSCOPE_EDITOR
304              Overrides  the EDITOR and VIEWER variables. Use this if you wish
305              to use a different editor with cscope  than  that  specified  by
306              your EDITOR/VIEWER variables.
307
308       CSCOPE_LINEFLAG
309              Format  of  the  line  number  flag for your editor. By default,
310              cscope invokes your editor via the  equivalent  of  ``editor  +N
311              file'',  where  ``N''  is the line number that the editor should
312              jump to. This format is used by both emacs and vi. If your  edi‐
313              tor needs something different, specify it in this variable, with
314              ``%s'' as a placeholder for the line number.  Ex: if your editor
315              needs  to be invoked as ``editor -#103 file'' to go to line 103,
316              set this variable to ``-#%s''.
317
318       CSCOPE_LINEFLAG_AFTER_FILE
319              Set this variable to ``yes'' if your editor needs to be  invoked
320              with  the line number option after the filename to be edited. To
321              continue the example from CSCOPE_LINEFLAG, above: if your editor
322              needs  to  see  ``editor  file  -#number'', set this environment
323              variable. Users of most standard editors (vi, emacs) do not need
324              to set this variable.
325
326       EDITOR Preferred editor, which defaults to vi.
327
328       HOME   Home directory, which is automatically set at login.
329
330       INCLUDEDIRS
331              Colon-separated  list  of  directories  to  search  for #include
332              files.
333
334       SHELL  Preferred shell, which defaults to sh.
335
336       SOURCEDIRS
337              Colon-separated list of directories  to  search  for  additional
338              source files.
339
340       TERM   Terminal type, which must be a screen terminal.
341
342       TERMINFO
343              Terminal  information directory full path name. If your terminal
344              is not in the standard terminfo directory, see curses  and  ter‐
345              minfo for how to make your own terminal description.
346
347       TMPDIR Temporary file directory, which defaults to /var/tmp.
348
349       VIEWER Preferred  file  display program (such as less), which overrides
350              EDITOR (see above).
351
352       VPATH  A colon-separated list of directories, each  of  which  has  the
353              same  directory  structure  below  it.  If  VPATH is set, cscope
354              searches for source files in the directories specified; if it is
355              not set, cscope searches only in the current directory.
356

FILES

358       cscope.files
359              Default files containing -I, -p, -q, and -T options and the list
360              of source files (overridden by the -i option).
361
362       cscope.out
363              Symbol cross-reference file (overridden by the -f option), which
364              is put in the home directory if it cannot be created in the cur‐
365              rent directory.
366
367       cscope.in.out
368       cscope.po.out
369              Default files containing the inverted index used for quick  sym‐
370              bol  searching  (-q  option). If you use the -f option to rename
371              the cross-reference file (so it's not cscope.out), the names for
372              these inverted index files will be created by adding
373               .in and .po to the name you supply with -f. For example, if you
374              indicated -f xyz, then these files would  be  named  xyz.in  and
375              xyz.po.
376
377       INCDIR Standard directory for #include files (usually /usr/include).
378

Notices

380       cscope recognizes function definitions of the form:
381       fname blank ( args ) white arg_decs white {
382
383       where: fname is the function name
384
385       blank  is  zero  or  more  spaces,  tabs, vtabs, form feeds or carriage
386              returns, not including newlines
387
388       args   is any string that does not contain a ``"'' or a newline
389
390       white  is zero or  more  spaces,  tabs,  vtabs,  form  feeds,  carriage
391              returns or newlines
392
393       arg_decs
394              are  zero  or  more  argument declarations (arg_decs may include
395              comments and white space)
396
397       It is not necessary for a function declaration to start at  the  begin‐
398       ning  of  a line. The return type may precede the function name; cscope
399       will still recognize the declaration. Function definitions that deviate
400       from this form will not be recognized by cscope.
401
402       The  ``Function''  column of the search output for the menu option Find
403       functions called by this function: input field will  only  display  the
404       first function called in the line, that is, for this function
405
406        e()
407        {
408                return (f() + g());
409        }
410
411       the display would be
412
413          Functions called by this function: e
414          File Function Line
415          a.c f 3 return(f() + g());
416
417       Occasionally,  a  function  definition  or  call  may not be recognized
418       because of braces inside #if statements. Similarly, the use of a  vari‐
419       able may be incorrectly recognized as a definition.
420
421       A  typedef  name preceding a preprocessor statement will be incorrectly
422       recognized as a global definition, for example,
423
424        LDFILE  *
425        #if AR16WR
426
427       Preprocessor statements can also prevent the recognition  of  a  global
428       definition, for example,
429
430        char flag
431        #ifdef ALLOCATE_STORAGE
432             = -1
433        #endif
434        ;
435
436       A function declaration inside a function is incorrectly recognized as a
437       function call, for example,
438
439        f()
440        {
441                void g();
442        }
443
444       is incorrectly recognized as a call to g.
445
446       cscope recognizes C++ classes by looking for  the  class  keyword,  but
447       doesn't  recognize  that a struct is also a class, so it doesn't recog‐
448       nize inline member function definitions in a structure. It also doesn't
449       expect  the class keyword in a typedef , so it incorrectly recognizes X
450       as a definition in
451
452        typedef class X  *  Y;
453
454       It also doesn't recognize operator function definitions
455
456        Bool Feature::operator==(const Feature & other)
457        {
458          ...
459        }
460
461       Nor does it recognize function  definitions  with  a  function  pointer
462       argument
463
464        ParseTable::Recognize(int startState, char *pattern,
465          int finishState, void (*FinalAction)(char *))
466        {
467          ...
468        }
469
470
471
472The Santa Cruz Operation          August 2003                        CSCOPE(1)
Impressum