.PU.TH CSCOPE "1" "August 2003" "The Santa Cruz Operation".SH NAMEcscope - interactively examine a C program .SH SYNOPSIS.B cscope.B [\-bCcdehkLlqRTUuVv].BI [\-F symfile ].BI [\-f reffile ].BI [\-I incdir ].BI [\-i namefile ].BI [\-[ 0-9 ] pattern ].BI [\-p n ].BI [\-s dir ].BI [ files ].SH DESCRIPTION.I cscopeis an interactive, screen-oriented tool that allows the user tobrowse through C source files for specified elements of code..PP   By default, .I cscopeexamines the C (.c and .h), lex (.l), and yacc (.y)source files in the current directory..I cscopemay also be invoked forsource files named on the command line. In either case, .I cscopesearches the standard directories for #include files that it does notfind in the current directory. .I cscopeuses a symbol cross-reference, called cscope.out by default, to locate functions, function calls, macros,variables, and preprocessor symbols in the files..PP   .I cscopebuilds the symbol cross-reference the first time it is used onthe source files for the program being browsed. On a subsequentinvocation, .I cscoperebuilds the cross-reference only if a source filehas changed or the list of source files is different. When thecross-reference is rebuilt, the data for the unchanged files arecopied from the old cross-reference, which makes rebuilding fasterthan the initial build..SH OPTIONS  Some command line arguments can only occur as the the ony argument inthe execution of cscope.  They cause the program to just print outsome output and exit immediately:.TP.B -hView the long usage help display..TP.B -VPrint on the first line of screen the version number of cscope..TP.B --helpSame as.B -h.TP.B --versionSame as.B -V.PPThe following options can appear in any combination:.TP.B -bBuild the cross-reference only..TP.B -CIgnore letter case when searching..TP.B -cUse only ASCII characters in the cross-reference file, that is,do not compress the data..TP.B -dDo not update the cross-reference..TP.B -eSuppress the <Ctrl>-e command prompt between files..TP.BI -F symfileRead symbol reference lines from .I symfile. (A symbol referencefile is created by > and >>, and can also be read using the <command, described under ``Issuing Subsequent Requests,''below.).TP.BI -f reffileUse .I reffile as the cross-reference file name instead of the default "cscope.out"..TP.BI -I incdirLook in .I incdir (before looking in $INCDIR, the standard placefor header files, normally /usr/include) for any #include fileswhose names do not begin with ``/'' and that are not specifiedon the command line or in .I namefile below. (The #include filesmay be specified with either double quotes or angle brackets.)The incdir directory is searched in addition to the currentdirectory (which is searched first) and the standard list(which is searched last). If more than one occurrence of -Iappears, the directories are searched in the order they appearon the command line..TP.BI -i namefileBrowse through all source files whose names are listed in .I namefile(file names separated by spaces, tabs, or new-lines) instead of thedefault name list file, which is called cscope.files. If this optionis specified, cscope ignores any file names appearing on the commandline. The argument namefile can be set to ``-'' to accept a list offiles from the standard input.  Filenames in the namefile that containwhitespace have to be enclosed in "double quotes".  Inside such quotedfilenames, any double-quote and backslash characters have to beescaped by backslashes..TP.B -k``Kernel Mode'', turns off the use of the default include dir(usually /usr/include) when building the database, since kernelsource trees generally do not use it..TP.B -LDo a single search with line-oriented output when used with the-num pattern option..TP.B -lLine-oriented interface (see ``Line-Oriented Interface''below)..TP.BI -[ "0-9" ] patternGo to input field .I num (counting from 0) and find .I pattern..TP.BI -P pathPrepend .I path to relative file names in a pre-built cross-reference file so you donot have to change to the directory where the cross-reference file wasbuilt. This option is only valid with the -d option..TP.BI -p nDisplay the last.I n file path components instead of the default (1). Use .I 0 to not display the file name at all..TP.B -qEnable fast symbol lookup via an inverted index. This optioncauses cscope to create 2 more files (default names``cscope.in.out'' and ``cscope.po.out'') in addition to the normaldatabase. This allows a faster symbol search algorithm thatprovides noticeably faster lookup performance for large projects..TP.B -RRecurse subdirectories during search for source files..TP.BI -s dirLook in.I dirfor additional source files. This option is ignored if source filesare given on the command line..TP.B -TUse only the first eight characters to match against C symbols.A regular expression containing special characters other than aperiod (.) will not match any symbol if its minimum length isgreater than eight characters..TP.B -UCheck file time stamps. This option will update the time stampon the database even if no files have changed..TP.B -uUnconditionally build the cross-reference file (assume that allfiles have changed)..TP.B -vBe more verbose in line-oriented mode.  Output progress updates duringdatabase building and searches..TP.I filesA list of file names to operate on..PPThe -I, -c, -k, -p, -q, and -T options can also be in the cscope.files file..PP.B Requesting the initial search.PPAfter the cross-reference is ready, cscope will display this menu:.PP.B Find this C symbol:.PD 0.TP.B  Find this function definition:.TP.B  Find functions called by this function:.TP.B  Find functions calling this function:.TP.B  Find this text string:.TP.B  Change this text string:.TP.B  Find this egrep pattern:.TP.B  Find this file:.TP.B  Find files #including this file:.PD 1.PPPress the <Up> or <Down> keys repeatedly to move to the desired inputfield, type the text to search for, and then press the <Return> key..PP.SH "Issuing subsequent requests"If the search is successful, any of these single-character commandscan be used:.TP.B 0-9a-zA-ZEdit the file referenced by the given line number..TP.B <Space>Display next set of matching lines..TP.B <Tab>Alternate between the menu and the list of matching lines.TP.B <Up>Move to the previous menu item (if the cursor is in the menu)or move to the previous matching line (if the cursor is in thematching line list.).TP.B <Down>Move to the next menu item (if the cursor is in the menu)or move to the next matching line (if the cursor is in thematching line list.).TP.B +Display next set of matching lines..TP.B - Display previous set of matching lines..TP.B ^eEdit displayed files in order..TP.B >Write the displayed list of lines to a file..TP.B >>Append the displayed list of lines to a file..TP.B <Read lines from a file that is in symbol reference format(created by > or >>), just like the -F option..TP.B ^Filter all lines through a shell command and display theresulting lines, replacing the lines that were already there..TP.B |Pipe all lines to a shell command and display them withoutchanging them..PPAt any time these single-character commands can also be used:.TP.B <Return>Move to next input field..TP.B ^nMove to next input field..TP.B ^pMove to previous input field..TP.B ^ySearch with the last text typed..TP.B ^bMove to previous input field and search pattern..TP.B ^fMove to next input field and search pattern..TP.B ^cToggle ignore/use letter case when searching. (When ignoringletter case, search for ``FILE'' will match ``File'' and