From ea376ff581dd55e756901822fb7239687ba522f9 Mon Sep 17 00:00:00 2001 From: Patrick McCarty Date: Fri, 12 Apr 2013 10:36:08 -0700 Subject: Imported Upstream version 15.8a --- doc/cscope.1 | 591 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 591 insertions(+) create mode 100644 doc/cscope.1 (limited to 'doc/cscope.1') diff --git a/doc/cscope.1 b/doc/cscope.1 new file mode 100644 index 0000000..6a3a86b --- /dev/null +++ b/doc/cscope.1 @@ -0,0 +1,591 @@ +.PU +.TH CSCOPE "1" "January 2007" "The Santa Cruz Operation" +.SH NAME +cscope - interactively examine a C program +.SH SYNOPSIS +.B cscope +.B [\-bCcdehkLlqRTUuVv] +.BI [\-F symfile ] +.BI [\-f reffile ] +.BI [\-I incdir ] +.BI [\-i namefile ] +.BI [\-0123456789 pattern ] +.BI [\-p n ] +.BI [\-s dir ] +.BI [ files ] +.SH DESCRIPTION +.I cscope +is an interactive, screen-oriented tool that allows the user to +browse through C source files for specified elements of code. +.PP +By default, +.I cscope +examines the C (.c and .h), lex (.l), and yacc (.y) +source files in the current directory. +.I cscope +may also be invoked for +source files named on the command line. In either case, +.I cscope +searches the standard directories for #include files that it does not +find in the current directory. +.I cscope +uses a symbol cross-reference, called +cscope.out by default, to locate functions, function calls, macros, +variables, and preprocessor symbols in the files. +.PP +.I cscope +builds the symbol cross-reference the first time it is used on +the source files for the program being browsed. On a subsequent +invocation, +.I cscope +rebuilds the cross-reference only if a source file +has changed or the list of source files is different. When the +cross-reference is rebuilt, the data for the unchanged files are +copied from the old cross-reference, which makes rebuilding faster +than the initial build. +.SH OPTIONS +Some command line arguments can only occur as the only argument in +the execution of cscope. They cause the program to just print out +some output and exit immediately: +.TP +.B -h +View the long usage help display. +.TP +.B -V +Print on the first line of screen the version number of cscope. +.TP +.B --help +Same as +.B -h +.TP +.B --version +Same as +.B -V + +.PP +The following options can appear in any combination: +.TP +.B -b +Build the cross-reference only. +.TP +.B -C +Ignore letter case when searching. +.TP +.B -c +Use only ASCII characters in the cross-reference file, that is, +do not compress the data. +.TP +.B -d +Do not update the cross-reference. +.TP +.B -e +Suppress the -e command prompt between files. +.TP +.BI -F symfile +Read symbol reference lines from +.I symfile. +(A symbol reference +file is created by > and >>, and can also be read using the < +command, described under ``Issuing Subsequent Requests'', +below.) +.TP +.BI -f reffile +Use +.I reffile +as the cross-reference file name instead of the default "cscope.out". +.TP +.BI -I incdir +Look in +.I incdir +(before looking in $INCDIR, the standard place +for header files, normally /usr/include) for any #include files +whose names do not begin with ``/'' and that are not specified +on the command line or in +.I namefile +below. (The #include files +may be specified with either double quotes or angle brackets.) +The incdir directory is searched in addition to the current +directory (which is searched first) and the standard list +(which is searched last). If more than one occurrence of -I +appears, the directories are searched in the order they appear +on the command line. +.TP +.BI -i namefile +Browse through all source files whose names are listed in +.I namefile +(file names separated by spaces, tabs, or new-lines) instead of the +default name list file, which is called cscope.files. If this option +is specified, cscope ignores any file names appearing on the command +line. The argument namefile can be set to ``-'' to accept a list of +files from the standard input. Filenames in the namefile that contain +whitespace have to be enclosed in "double quotes". Inside such quoted +filenames, any double-quote and backslash characters have to be +escaped by backslashes. +.TP +.B -k +``Kernel Mode'', turns off the use of the default include dir +(usually /usr/include) when building the database, since kernel +source trees generally do not use it. +.TP +.B -L +Do a single search with line-oriented output when used with the +-num pattern option. +.TP +.B -l +Line-oriented interface (see ``Line-Oriented Interface'' +below). +.TP +.BI -[ "0-9" ] pattern +Go to input field +.I num +(counting from 0) and find +.I pattern. +.TP +.BI -P path +Prepend +.I path +to relative file names in a pre-built cross-reference file so you do +not have to change to the directory where the cross-reference file was +built. This option is only valid with the -d option. +.TP +.BI -p n +Display the last +.I n +file path components instead of the default (1). Use +.I 0 +not to display the file name at all. +.TP +.B -q +Enable fast symbol lookup via an inverted index. This option +causes cscope to create 2 more files (default names +``cscope.in.out'' and ``cscope.po.out'') in addition to the normal +database. This allows a faster symbol search algorithm that +provides noticeably faster lookup performance for large projects. +.TP +.B -R +Recurse subdirectories during search for source files. +.TP +.BI -s dir +Look in +.I dir +for additional source files. This option is ignored if source files +are given on the command line. +.TP +.B -T +Use only the first eight characters to match against C symbols. +A regular expression containing special characters other than a +period (.) will not match any symbol if its minimum length is +greater than eight characters. +.TP +.B -U +Check file time stamps. This option will update the time stamp +on the database even if no files have changed. +.TP +.B -u +Unconditionally build the cross-reference file (assume that all +files have changed). +.TP +.B -v +Be more verbose in line-oriented mode. Output progress updates during +database building and searches. +.TP +.I files +A list of file names to operate on. +.PP +The -I, -c, -k, -p, -q, and -T options can also be in the cscope.files file. +.PP +.SS Requesting the initial search +.PP +After 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 +.PP +Press the or keys repeatedly to move to the desired input +field, type the text to search for, and then press the key. +.PP +.SS "Issuing subsequent requests" +If the search is successful, any of these single-character commands +can be used: +.TP +.B 0-9a-zA-Z +Edit the file referenced by the given line number. +.TP +.B +Display next set of matching lines. +.TP +.B +Alternate between the menu and the list of matching lines +.TP +.B +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 the +matching line list.) +.TP +.B +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 the +matching line list.) +.TP +.B + +Display next set of matching lines. +.TP +.B - +Display previous set of matching lines. +.TP +.B ^e +Edit 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 the +resulting lines, replacing the lines that were already there. +.TP +.B | +Pipe all lines to a shell command and display them without +changing them. +.PP +At any time these single-character commands can also be used: +.TP +.B +Move to next input field. +.TP +.B ^n +Move to next input field. +.TP +.B ^p +Move to previous input field. +.TP +.B ^y +Search with the last text typed. +.TP +.B ^b +Move to previous input field and search pattern. +.TP +.B ^f +Move to next input field and search pattern. +.TP +.B ^c +Toggle ignore/use letter case when searching. (When ignoring +letter case, search for ``FILE'' will match ``File'' and +``file''.) +.TP +.B ^r +Rebuild the cross-reference. +.TP +.B ! +Start an interactive shell (type ^d to return to cscope). +.TP +.B ^l +Redraw the screen. +.TP +.B ? +Give help information about cscope commands. +.TP +.B ^d +Exit cscope. +.PP +.PP +.B NOTE: If the first character of the text to be searched for matches +.B one of the above commands, escape it by typing a (backslash) first. +.PP +.B Substituting new text for old text +.PP +After the text to be changed has been typed, cscope will prompt for +the new text, and then it will display the lines containing the old +text. Select the lines to be changed with these single-character +commands: +.PP +.TP +.B 0-9a-zA-Z +Mark or unmark the line to be changed. +.TP +.B * +Mark or unmark all displayed lines to be changed. +.TP +.B +Display next set of lines. +.TP +.B + +Display next set of lines. +.TP +.B - +Display previous set of lines. +.TP +.B a +Mark or unmark all lines to be changed. +.TP +.B ^d +Change the marked lines and exit. +.TP +.B +Exit without changing the marked lines. +.TP +.B ! +Start an interactive shell (type ^d to return to cscope). +.TP +.B ^l +Redraw the screen. +.TP +.B ? +Give help information about cscope commands. +.TP +.B Special keys +If your terminal has arrow keys that work in vi, you can use them +to move around the input fields. The up-arrow key is useful to move to +the previous +input field instead of using the key repeatedly. If you have +, , or keys they will act as the ^l, +, and - +commands, respectively. +.PP +.SS Line-Oriented interface +.PP +The -l option lets you use cscope where a screen-oriented interface +would not be useful, for example, from another screen-oriented +program. +.PP +cscope will prompt with >> when it is ready for an input line starting +with the field number (counting from 0) immediately followed by the +search pattern, for example, ``lmain'' finds the definition of the +main function. +.PP +If you just want a single search, instead of the -l option use the -L +and -num pattern options, and you won't get the >> prompt. +.PP +For -l, cscope outputs the number of reference lines +cscope: 2 lines +.PP +For each reference found, cscope outputs a line consisting of the file +name, function name, line number, and line text, separated by spaces, +for example, +main.c main 161 main(argc, argv) +.PP +Note that the editor is not called to display a single reference, +unlike the screen-oriented interface. +.PP +You can use the c command to toggle ignore/use letter case when +searching. (When ignoring letter case, search for ``FILE'' will match +``File'' and ``file''.) +.PP +You can use the r command to rebuild the database. +.PP +cscope will quit when it detects end-of-file, or when the first +character of an input line is ``^d'' or ``q''. +.PP +.SH "ENVIRONMENT VARIABLES" +.TP +.B CSCOPE_EDITOR +Overrides the EDITOR and VIEWER variables. Use this if you wish to use +a different editor with cscope than that specified by your +EDITOR/VIEWER variables. +.TP +.B CSCOPE_LINEFLAG +Format of the line number flag for your editor. By default, cscope +invokes your editor via the equivalent of ``editor +N file'', where +``N'' is the line number that the editor should jump to. This format +is used by both emacs and vi. If your editor needs something +different, specify it in this variable, with ``%s'' as a placeholder +for the line number. Ex: if your editor needs to be invoked as +``editor -#103 file'' to go to line 103, set this variable to +``-#%s''. +.TP +.B CSCOPE_LINEFLAG_AFTER_FILE +Set this variable to ``yes'' if your editor needs to be invoked with +the line number option after the filename to be edited. To continue +the example from CSCOPE_LINEFLAG, above: if your editor needs to see +``editor file -#number'', set this environment variable. Users of most +standard editors (vi, emacs) do not need to set this variable. +.TP +.B EDITOR +Preferred editor, which defaults to vi. +.TP +.B HOME +Home directory, which is automatically set at login. +.TP +.B INCLUDEDIRS +Colon-separated list of directories to search for #include +files. +.TP +.B SHELL +Preferred shell, which defaults to sh. +.TP +.B SOURCEDIRS +Colon-separated list of directories to search for additional +source files. +.TP +.B TERM +Terminal type, which must be a screen terminal. +.TP +.B TERMINFO +Terminal information directory full path name. If your terminal +is not in the standard terminfo directory, see curses +and terminfo for how to make your own terminal description. +.TP +.B TMPDIR +Temporary file directory, which defaults to /var/tmp. +.TP +.B VIEWER +Preferred file display program (such as less), which overrides +EDITOR (see above). +.TP +.B VPATH +A colon-separated list of directories, each of which has the +same directory structure below it. If VPATH is set, cscope +searches for source files in the directories specified; if it +is not set, cscope searches only in the current directory. +.PP +.SH FILES +.TP +.B cscope.files +Default files containing -I, -p, -q, and -T options and the +list of source files (overridden by the -i option). +.TP +.B cscope.out +Symbol cross-reference file (overridden by the -f option), +which is put in the home directory if it cannot be created in +the current directory. +.TP +.PD 0 +.B cscope.in.out +.TP +.B cscope.po.out +.PD 1 +Default files containing the inverted index used for quick +symbol searching (-q option). If you use the -f option to +rename the cross-reference file (so it's not cscope.out), the +names for these inverted index files will be created by adding + .in and .po to the name you supply with -f. For example, if you +indicated -f xyz, then these files would be named xyz.in and +xyz.po. +.TP +.B INCDIR +Standard directory for #include files (usually /usr/include). +.SH Notices +.I cscope +recognizes function definitions of the form: +.PD 0 +.TP +fname blank ( args ) white arg_decs white { +.PD 1 +.TP +where: +.I fname +is the function name +.TP +.I blank +is zero or more spaces, tabs, vtabs, form feeds or carriage returns, +not including newlines +.TP +.I args +is any string that does not contain a ``"'' or a newline +.TP +.I white +is zero or more spaces, tabs, vtabs, form feeds, carriage returns or newlines +.TP +.I arg_decs +are zero or more argument declarations (arg_decs may include +comments and white space) +.PP +It is not necessary for a function declaration to start at the +beginning of a line. The return type may precede the function name; +cscope will still recognize the declaration. Function definitions that +deviate from this form will not be recognized by cscope. +.PP +The ``Function'' column of the search output for the menu option Find +functions called by this function: input field will only display the +first function called in the line, that is, for this function +.PP + e() + { + return (f() + g()); + } +.PP +the display would be +.PP + Functions called by this function: e + File Function Line + a.c f 3 return(f() + g()); +.PP +Occasionally, a function definition or call may not be recognized +because of braces inside #if statements. Similarly, the use of a +variable may be incorrectly recognized as a definition. +.PP +A +.B typedef +name preceding a preprocessor statement will be incorrectly +recognized as a global definition, for example, +.PP + LDFILE * + #if AR16WR +.PP +Preprocessor statements can also prevent the recognition of a global +definition, for example, +.PP + char flag + #ifdef ALLOCATE_STORAGE + = -1 + #endif + ; +.PP +A function declaration inside a function is incorrectly recognized as +a function call, for example, +.PP + f() + { + void g(); + } +.PP +is incorrectly recognized as a call to g. +.PP +.I cscope +recognizes C++ classes by looking for the class keyword, but +doesn't recognize that a struct is also a class, so it doesn't +recognize inline member function definitions in a structure. It also +doesn't expect the class keyword in a +.I typedef +, so it incorrectly +recognizes X as a definition in +.PP + typedef class X * Y; +.PP +It also doesn't recognize operator function definitions +.PP + Bool Feature::operator==(const Feature & other) + { + ... + } +.PP +Nor does it recognize function definitions with a function pointer +argument +.PP + ParseTable::Recognize(int startState, char *pattern, + int finishState, void (*FinalAction)(char *)) + { + ... + } -- cgit v1.2.3