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

NAME

6       cscope - interactively examine a C program
7

SYNOPSIS

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

ENVIRONMENT VARIABLES

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

FILES

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

Notices

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