CSCOPE(1) CSCOPE(1)
NAME
cscope - interactively examine a C program
Cscope- 交互检查一个C程序。
SYNOPSIS
cscope [-bCcdehkLlqRTUuVv] [-Fsymfile] [-freffile] [-Iincdir] [-iname‐
file] [-0123456789pattern] [-pn] [-sdir] [files]
DESCRIPTION
cscope is an interactive, screen-oriented tool that allows the user to
browse through C source files for specified elements of code.
By default, cscope examines the C (.c and .h), lex (.l), and yacc (.y)
source files in the current directory. cscope may also be invoked for
source files named on the command line. In either case, cscope searches
the standard directories for #include files that it does not find in
the current directory. cscope uses a symbol cross-reference, called
cscope.out by default, to locate functions, function calls, macros,
variables, and preprocessor symbols in the files.
cscope builds the symbol cross-reference the first time it is used on
the source files for the program being browsed. On a subsequent invoca‐
tion, cscope rebuilds the cross-reference only if a source file has
changed or the list of source files is different. When the cross-refer‐
ence is rebuilt, the data for the unchanged files are copied from the
old cross-reference, which makes rebuilding faster than the initial
build.
Cscope是一个交互式的,基于屏幕的工具,允许用户浏览指定的代码元素,通过C
源文件。默认的,cscope 检查当前目录以下扩展名的文件:.c .h .l .y 。
cscope也可能会被被命名在cmd里的源文件调用。在其他情况下,如果在当前目录
没有找到#include包含的文件,cscope会去搜索标准目录。Cscope使用一个符号
交叉引用,默认叫做cscope.out,用这个文件来定位函数、函数调用、宏、变量、
和预处理符号。Cscope在它第一次被用的时候构建符号交叉引用。在随后的调用中,
cscope只会在有源文件被修改或者源文件列表不同的时候重建交叉引用。当交叉引
用被重建,未更改源文件对应的数据将会被从旧的交叉引用复制,这样重建会比
整个重建快很多。
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:
一些cmd参数只能以cscope执行需要的参数存在。它们只会引起一些输出,并且会立即退出。
-h 显示很长的用户帮助。
-V 输出cscope的版本号到屏幕的第一行。
--help 和–h一样。
--version和 –V一样。
The following options can appear in any combination:
下面的选项能出现在任何的组合:
-b Build the cross-reference only.
只创建交叉引用,不显示交互窗口。
-C Ignore letter case when searching.
忽略搜索时的大小写。
-c Use only ASCII characters in the cross-reference file, that is,
do not compress the data.
在交叉引用文件里只使用ASCII字符集,就是说,不会压缩数据。
-d Do not update the cross-reference.
不会更新交叉引用。
-e Suppress the <Ctrl>-e command prompt between files.
通过按下ctrl+e 快速在两个文件中切换。
-Fsymfile
Read symbol reference lines from symfile. (A symbol reference
file is created by > and >>, and can also be read using the <
command, described under ``Issuing Subsequent Requests'',
below.)
从symfile文件里读取符号引用行。(一个符号引用文件通过 >,>>创建, 并且也能被< 读取,
在“Issuing Subsequent Requests”后边有描述)
-freffile
Use reffile as the cross-reference file name instead of the
default "cscope.out".
使用 reffile 作为交叉引用文件的名字,代替默认的 cscope.out
-Iincdir
Look in 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 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.
在incdir(在查找$INCDIR之前,头文件的标准位置,通常是/usr/include)
里查找任何#include 文件,这些文件的名字不以“/”开始,并且没有被指
定在cmd或者在namefile里。(#include 文件也可能会被指定为其他的
双引号或角括号)除了搜索当前目录和标准列表(被最后一个搜索),
那个incdir目录也会被搜索。如果有多于一个这样的事物(-I相关)
出现,这个目录将会按照他出现在cmd里的顺序被搜索。
-inamefile
Browse through all source files whose names are listed in name‐
file (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 file‐
names, any double-quote and backslash characters have to be
escaped by backslashes.
浏览所有名字被列在namefile里的源文件,替代默认的name 列表文件,
默认的被叫做“cscope.files”。如果这个选项被指定,cscope 将会忽略
所有出现在cmd里的文件名。这个namefile参数能被设置“-”,用以接收
从标准输入获取的文件列表。在namefile里的包含空格的文件名比如被
双引号包裹。在这些被包裹的文件名里,任何双引号、转义字符必须被
反斜杠转换。
-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.
用来关掉默认包含“/usr/include”这样目录用途的,在构建数据库的时候,因为内核源文件数通常不会使用。
-L Do a single search with line-oriented output when used with the
-num pattern option.
做一个单独的基于行输出的搜索,当使用–num模式选项时。
-l Line-oriented interface (see ``Line-Oriented Interface'' below).
基于行交互(“可以看下面的“Line-Oriented Interface””)。
-[0-9]pattern
Go to input field num (counting from 0) and find pattern.
去对应的输入字段(从0开始计算),并且查找模式
-Ppath Prepend path to relative file names in a pre-built cross-refer‐
ence 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.
前缀路径,用于相对文件名,在预建交叉引用文件时,那样你就没必要在交叉引用文件被创建时改变目录。这个选项只在有“-d”时有效。
-pn Display the last n file path components instead of the default
(1). Use 0 not to display the file name at all.
显示最后N个文件路径组件,代替默认值(1),使用0表示不会显示文件名。
-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 nor‐
mal database. This allows a faster symbol search algorithm that
provides noticeably faster lookup performance for large
projects.
通过一个反向索引启用加速符号查找。这个选项会引起cscope额外创建2个文件(默认名字是“cscope.in.out”、“cscope.po.out”)并且附加在正常的数据库上。
这会允许一个快速查询算法,这个算法能显著提高搜索效率,在针对大项目时。
-R Recurse subdirectories during search for source files.
在搜索源文件时,递归搜索子目录。
-sdir Look in dir for additional source files. This option is ignored
if source files are given on the command line.
在目录里搜索附加的源文件,当源文件在cmd被给定时,这个选项将被忽略。
-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.
只用第一个八个字符来匹配一个C语言符号。如果一个正则表达式大于八个字符,那么,在包含除了.号的指定字符 时,它将不匹配任何符号。
-U Check file time stamps. This option will update the time stamp
on the database even if no files have changed.
检查文件的时间戳。这个选项将会更新数据库里的时间戳,即使没有文件被改变。
-u Unconditionally build the cross-reference file (assume that all
files have changed).
无条件的构建交叉引用文件(假定所有文件被更改)。
-v Be more verbose in line-oriented mode. Output progress updates
during database building and searches.
基于行模式下更详细的输出。在数据库构建和搜索中,输出进度更新。
files A list of file names to operate on.
一个需要被搜索的文件名的列表。
The -I, -c, -k, -p, -q, and -T options can also be in the cscope.files
file.
-I, -c, -k, -p, -q, -T 这几个选项也能出现在cscope.files文件里。
Requesting the initial search
After the cross-reference is ready, cscope will display this menu:
请求最初的搜索
在交叉引用被准备完成后,cscope将会显示如下这个菜单:
Find this C symbol:
Find this function 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:
Press the <Up> or <Down> keys repeatedly to move to the desired input
field, type the text to search for, and then press the <Return> key.
按下<Up> 或者 <Down> 按键反复在以上的需要的字段中移动。按下return返回。
Issuing subsequent requests
If the search is successful, any of these single-character commands can
be used:
发动随后的请求
如果搜索是成功的,那么以下这些单字符命令就能被使用。
0-9a-zA-Z
Edit the file referenced by the given line number.
编辑那个被给定行号引用的文件。
<Space>
Display next set of matching lines.
显示匹配行的下一个集合。
<Tab> Alternate between the menu and the list of matching lines
在主菜单和匹配行结果中来回切换。
<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 the
matching line list.)
移动到前一个菜单项(如果光标在菜单里)或者移动到前一个匹配行(如果光标在匹配行列表)。
<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 the matching
line list.)
移动到下一个菜单项(如果光标在菜单)或者移动到下一个匹配行(如果光标在匹配行列表)。
+ Display next set of matching lines.
显示下一个匹配行集合。
- Display previous set of matching lines.
显示前一个匹配行集合。
^e Edit displayed files in order.
按顺序编辑被显示的文件。
> Write the displayed list of lines to a file.
把被显示行的列表写到一个文件里。
>> Append the displayed list of lines to a file.
追加被显示行的列表到一个文件里。
< Read lines from a file that is in symbol reference format (cre‐
ated by > or >>), just like the -F option.
从一个文件里读取行,这个文件时一个符号引用格式的(被> >>创建),就像 -F选项。
^ Filter all lines through a shell command and display the result‐
ing lines, replacing the lines that were already there.
过滤所有行,通过一个shell命令,并且显示结果行,替换已经在那的行。
| Pipe all lines to a shell command and display them without
changing them.
通过管道,将所有行导入一个shell命令,并且在显示它们的同时不会更改它们。
At any time these single-character commands can also be used:
在任何时候这些单字符命令也能被这么用:
<Return>
Move to next input field.
移动到下一个输入字段
^n Move to next input field.
移动到下一个输入字段
^p Move to previous input field.
移动到前一个输入字段
^y Search with the last text typed.
用最后文本指定的类型搜索。
^b Move to previous input field and search pattern.
移动到前一个输入字段并且搜索模式。
^f Move to next input field and searchpattern.
移动到下一个输入字段并且搜索模式。
^c Toggle ignore/use letter case when searching. (When ignoring
letter case, search for ``FILE'' will match ``File'' and
``file''.)
触发 忽略/使用 大小写敏感的开关,在搜索时。(当忽略大小写时,搜索“FILE”将会匹配
“File”和“file”)。
^r Rebuild the cross-reference.
重建交叉引用。
! Start an interactive shell (type ^d to return to cscope).
开始一个交互的shell(命令^d 会从cscope返回)。
^l Redraw the screen.
重画屏幕。
? Give help information about cscope commands.
获取关于cscope命令的帮助信息。
^d Exit cscope.
退出cscope。
NOTE: If the first character of the text to be searched for matches one
of the above commands, escape it by typing a (backslash) first.
注意:如果第一个用来被搜索的text的字符匹配任意以上一个命令,请首先用一个反斜杠定义来避免它。
Substituting new text for old text
将旧文本替换为新文本。
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:
在这个需要被改变的文本已经被类型化后,cscope将会为新文本做提示,并且将会
显示包含旧文本的行。用下面这些单字符命令选择需要被改变的行。
0-9a-zA-Z
Mark or unmark the line to be changed.
标记或取消标记需要被修改的行
* Mark or unmark all displayed lines to be changed.
标记或取消标记显示所有需要被修改的行
<Space>
Display next set of lines.
显示下一个行集合
+ Display next set of lines.
显示下一个行集合。
- Display previous set of lines.
显示上一个行集合
a Mark or unmark all lines to be changed.
标记或取消标记显示所有需要被修改的行
^d Change the marked lines and exit.
修改被标记的行并且退出。
<Esc> Exit without changing the marked lines.
退出并且不修改被标记的行。
! Start an interactive shell (type ^d to return to cscope).
开始一个交互Shell(命令 ^d 返回cscope)。
^l Redraw the screen.
重画屏幕。
? Give help information about cscope commands.
获取关于cscope命令的帮助信息。
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 <Tab>
key repeatedly. If you have <CLEAR>, <NEXT>, or <PREV> keys they
will act as the ^l, +, and - commands, respectively.
特别按键
如果你的终端有方向键,在VI里能工作的方向键,你能用它们在输入字段里走来走去。
上方向键被用来移动到前一个输入字段,代替反复使用TAB键。如果你有CLEAR、NEXT、或PREV
键,那它们将会分别担当^l, +, 和 - 命令。
Line-Oriented interface
The -l option lets you use cscope where a screen-oriented interface
would not be useful, for example, from another screen-oriented program.
基于行交互
-l选项让你这样使用cscope,在基于屏幕交互不可用的时候。比如,从其他基于屏幕
交互的程序。
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.
cscope将会用>>来提示,在它准备好的时候,准备好为一个开始在字段编号的输入行
立即跟随搜索模式。例如,“lmain” 会查找main函数的定义。
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.
如果你只想要一个单纯的搜索,用-L选项和-num模式选项来替代-l选项,并且你
不用获取>>提示。
For -l, cscope outputs the number of reference lines cscope: 2 lines
对于-l,cscope输出被引用行的数量:2行
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)
对于每个被找到的引用,cscope输出一个行,这个行由文件名,函数名,行号和
行文本组成,由空格隔开。
Note that the editor is not called to display a single reference,
unlike the screen-oriented interface.
注意那个编辑器不会被调用来显示一个单独的引用,不像基于屏幕的交互。
You can use the c command to toggle ignore/use letter case when search‐
ing. (When ignoring letter case, search for ``FILE'' will match
``File'' and ``file''.)
在搜索时,你能用c命令来开关忽略大小写的开关。(当选择忽略大小写时,搜索
“FILE”将会匹配“File”和“file”。)
You can use the r command to rebuild the database.
你能用r命令来重建数据库。
cscope will quit when it detects end-of-file, or when the first charac‐
ter of an input line is ``^d'' or ``q''.
当它检测到文件结尾时cscope将会退出,或者当第一个输入行的字符是“^d” 或“q”。
ENVIRONMENT VARIABLES
环境变量
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.
cscope编辑器
覆盖那个EDITOR和VIEWER变量。如果你希望在cscope里使用不同的编辑器,
通过指定这两个变量。
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 edi‐
tor 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''.
cscope行标记
你的编辑器的行标记的格式。默认的,cscope调用你的编辑器通过等同于
“editor +N file”这样的命令调用,当“N”时一个行号时,编辑器将会跳入。
这个格式被用在emacs和vi。如果你的编辑器需要做不同的事情,用这个变量
指定,用“%s”作为一个行号的占位符。除了:如果你的编辑器需要被这么调用,
“editor -#103 file”,将会到文件的103行,设置这个变量为“-#%s”。
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.
在文件后边的cscope行标记
如果你的编辑器需要被这样调用,把行号放在需要被编辑的文件名之后,
那么设置这个变量为“yes”。继续从《cscope行标记》这段的例子,如果
你的编辑器需要看``editor file -#number'',那就设置这个环境变量。
大多数标准编辑器(vi,emacs)的用户都不需要设置这个变量。
EDITOR Preferred editor, which defaults to vi.
编辑器 首选编辑器 它默认是vi。
HOME Home directory, which is automatically set at login.
HOME HOME目录,在登录时被自动设置。
INCLUDEDIRS
Colon-separated list of directories to search for #include
files.
包含目录
用冒号分割的一个目录列表,用来搜索#include 包含的文件。
SHELL Preferred shell, which defaults to sh.
首选shell,默认是sh。
SOURCEDIRS
Colon-separated list of directories to search for additional
source files.
源文件路径
用冒号分割的目录列表,用来搜索附加的源文件。
TERM Terminal type, which must be a screen terminal.
TERM 终端类型,比如时一个屏幕终端。
TERMINFO
Terminal information directory full path name. If your terminal
is not in the standard terminfo directory, see curses and ter‐
minfo for how to make your own terminal description.
终端信息目录的全路径名。如果你的终端不实在标准终端信息路径,可以
看 curses 和 terminfo 如果描述你自己的终端。
TMPDIR Temporary file directory, which defaults to /var/tmp.
临时目录 临时文件目录,默认是/var/tmp.
VIEWER Preferred file display program (such as less), which overrides
EDITOR (see above).
首选文件显示程序,覆盖编辑器。
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.
一个用冒号分割的目录列表,它们的每一个都用相通的目录结构。如果VPATH被
设置,cscope将会搜索这个目录指定的源文件。如果它没有被设置,cscope将
之后搜索当前目录。
FILES
cscope.files
Default files containing -I, -p, -q, and -T options and the list
of source files (overridden by the -i option).
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 cur‐
rent directory.
符号交叉引用文件(被-f选项重写),如果它不能在当前目录被创建,
那么它就会被放在home目录。
cscope.in.out
cscope.po.out
Default files containing the inverted index used for quick sym‐
bol 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.
包含用来快速查找系统符号(-q选项)的反向索引的默认文件。如果你
用-f选项来重命名交叉引用文件(那么它就不能时cscope.out),这些
反向索引文件将会被创建成,用你-f提供的名字再附加上.in和.po。例
如,如果你指明 -f xyz,那么这两个文件将会被命名为 xyz.in 和xyz.out。
INCDIR Standard directory for #include files (usually /usr/include).
#include 包含文件的标准目录(通常是 /usr/include)。
Notices
注意
cscope recognizes function definitions of the form:
fname blank ( args ) white arg_decs white {
cscope能辨认出的函数定义的格式:
where: fname is the function name
fname是函数的名字
blank is zero or more spaces, tabs, vtabs, form feeds or carriage
returns, not including newlines
是零或多个空格、tabs, vtabs,换行符或回车,不包含新行。
args is any string that does not contain a ``"'' or a newline
是任何不包含``"''或一个新行的字符串。
white is zero or more spaces, tabs, vtabs, form feeds, carriage
returns or newlines
是零或多个空格、tabs, vtabs,换行符或回车,新行。
arg_decs
are zero or more argument declarations (arg_decs may include
comments and white space)
是零或多个参数声明(arg_decs 有可能会包含注释和空格)
It is not necessary for a function declaration to start at the begin‐
ning 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.
一个函数声明开始在一行的开始不是必要的。返回类型有可能出现在函数名前面。
cscope将会一直辨认那个声明。脱离这种格式的函数定义将不会被cscope辨认。
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
这个搜索输出的列``Function'',查找被这个函数调用的函数:输入字段将只会
显示第一个在这个行被调用的函数,就像下面这个函数
e()
{
return (f() + g());
}
the display would be
Functions called by this function: e
File Function Line
a.c f 3 return(f() + g());
Occasionally, a function definition or call may not be recognized
because of braces inside #if statements. Similarly, the use of a vari‐
able may be incorrectly recognized as a definition.
偶尔的,一个函数定义或调用可能不会被辨认出来,因为括号里面的#if语句。同样
的,一个变量的使用也可能会被不正确的辨认为一个定义。
A typedef name preceding a preprocessor statement will be incorrectly
recognized as a global definition, for example,
一个 typedef 名字先于一个预处理语句将会被不正确的辨认为一个全局定义,例如,
LDFILE *
#if AR16WR
Preprocessor statements can also prevent the recognition of a global
definition, for example,
预处理语句也能阻止一个全局定义的辨认,例如,
char flag
#ifdef ALLOCATE_STORAGE
= -1
#endif
;
A function declaration inside a function is incorrectly recognized as a
function call, for example,
一个函数声明在一个函数里,会被不正确的辨认为一个函数调用,例如,
f()
{
void g();
}
is incorrectly recognized as a call to g.
被不正确的辨认为一个调用g函数。
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 recog‐
nize inline member function definitions in a structure. It also doesn't
expect the class keyword in a typedef , so it incorrectly recognizes X
as a definition in
cscope通过查找类关键字来辨认C++的类,但是不会辨认出一个结构也是一个类,
所以它不能辨认出定义在一个结构内的内联成员函数。它也不希望类关键字用
typedef,那么它会不正确的辨认出X 是一个定义。
typedef class X * Y;
It also doesn't recognize operator function definitions
它也不会辨认出操作符函数定义
Bool Feature::operator==(const Feature & other)
{
...
}
Nor does it recognize function definitions with a function pointer
argument
它也不能辨认一个函数指针参数。
ParseTable::Recognize(int startState, char *pattern,
int finishState, void (*FinalAction)(char *))
{
...
}
The Santa Cruz Operation January 2007 CSCOPE(1)
NAME
cscope - interactively examine a C program
Cscope- 交互检查一个C程序。
SYNOPSIS
cscope [-bCcdehkLlqRTUuVv] [-Fsymfile] [-freffile] [-Iincdir] [-iname‐
file] [-0123456789pattern] [-pn] [-sdir] [files]
DESCRIPTION
cscope is an interactive, screen-oriented tool that allows the user to
browse through C source files for specified elements of code.
By default, cscope examines the C (.c and .h), lex (.l), and yacc (.y)
source files in the current directory. cscope may also be invoked for
source files named on the command line. In either case, cscope searches
the standard directories for #include files that it does not find in
the current directory. cscope uses a symbol cross-reference, called
cscope.out by default, to locate functions, function calls, macros,
variables, and preprocessor symbols in the files.
cscope builds the symbol cross-reference the first time it is used on
the source files for the program being browsed. On a subsequent invoca‐
tion, cscope rebuilds the cross-reference only if a source file has
changed or the list of source files is different. When the cross-refer‐
ence is rebuilt, the data for the unchanged files are copied from the
old cross-reference, which makes rebuilding faster than the initial
build.
Cscope是一个交互式的,基于屏幕的工具,允许用户浏览指定的代码元素,通过C
源文件。默认的,cscope 检查当前目录以下扩展名的文件:.c .h .l .y 。
cscope也可能会被被命名在cmd里的源文件调用。在其他情况下,如果在当前目录
没有找到#include包含的文件,cscope会去搜索标准目录。Cscope使用一个符号
交叉引用,默认叫做cscope.out,用这个文件来定位函数、函数调用、宏、变量、
和预处理符号。Cscope在它第一次被用的时候构建符号交叉引用。在随后的调用中,
cscope只会在有源文件被修改或者源文件列表不同的时候重建交叉引用。当交叉引
用被重建,未更改源文件对应的数据将会被从旧的交叉引用复制,这样重建会比
整个重建快很多。
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:
一些cmd参数只能以cscope执行需要的参数存在。它们只会引起一些输出,并且会立即退出。
-h 显示很长的用户帮助。
-V 输出cscope的版本号到屏幕的第一行。
--help 和–h一样。
--version和 –V一样。
The following options can appear in any combination:
下面的选项能出现在任何的组合:
-b Build the cross-reference only.
只创建交叉引用,不显示交互窗口。
-C Ignore letter case when searching.
忽略搜索时的大小写。
-c Use only ASCII characters in the cross-reference file, that is,
do not compress the data.
在交叉引用文件里只使用ASCII字符集,就是说,不会压缩数据。
-d Do not update the cross-reference.
不会更新交叉引用。
-e Suppress the <Ctrl>-e command prompt between files.
通过按下ctrl+e 快速在两个文件中切换。
-Fsymfile
Read symbol reference lines from symfile. (A symbol reference
file is created by > and >>, and can also be read using the <
command, described under ``Issuing Subsequent Requests'',
below.)
从symfile文件里读取符号引用行。(一个符号引用文件通过 >,>>创建, 并且也能被< 读取,
在“Issuing Subsequent Requests”后边有描述)
-freffile
Use reffile as the cross-reference file name instead of the
default "cscope.out".
使用 reffile 作为交叉引用文件的名字,代替默认的 cscope.out
-Iincdir
Look in 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 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.
在incdir(在查找$INCDIR之前,头文件的标准位置,通常是/usr/include)
里查找任何#include 文件,这些文件的名字不以“/”开始,并且没有被指
定在cmd或者在namefile里。(#include 文件也可能会被指定为其他的
双引号或角括号)除了搜索当前目录和标准列表(被最后一个搜索),
那个incdir目录也会被搜索。如果有多于一个这样的事物(-I相关)
出现,这个目录将会按照他出现在cmd里的顺序被搜索。
-inamefile
Browse through all source files whose names are listed in name‐
file (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 file‐
names, any double-quote and backslash characters have to be
escaped by backslashes.
浏览所有名字被列在namefile里的源文件,替代默认的name 列表文件,
默认的被叫做“cscope.files”。如果这个选项被指定,cscope 将会忽略
所有出现在cmd里的文件名。这个namefile参数能被设置“-”,用以接收
从标准输入获取的文件列表。在namefile里的包含空格的文件名比如被
双引号包裹。在这些被包裹的文件名里,任何双引号、转义字符必须被
反斜杠转换。
-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.
用来关掉默认包含“/usr/include”这样目录用途的,在构建数据库的时候,因为内核源文件数通常不会使用。
-L Do a single search with line-oriented output when used with the
-num pattern option.
做一个单独的基于行输出的搜索,当使用–num模式选项时。
-l Line-oriented interface (see ``Line-Oriented Interface'' below).
基于行交互(“可以看下面的“Line-Oriented Interface””)。
-[0-9]pattern
Go to input field num (counting from 0) and find pattern.
去对应的输入字段(从0开始计算),并且查找模式
-Ppath Prepend path to relative file names in a pre-built cross-refer‐
ence 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.
前缀路径,用于相对文件名,在预建交叉引用文件时,那样你就没必要在交叉引用文件被创建时改变目录。这个选项只在有“-d”时有效。
-pn Display the last n file path components instead of the default
(1). Use 0 not to display the file name at all.
显示最后N个文件路径组件,代替默认值(1),使用0表示不会显示文件名。
-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 nor‐
mal database. This allows a faster symbol search algorithm that
provides noticeably faster lookup performance for large
projects.
通过一个反向索引启用加速符号查找。这个选项会引起cscope额外创建2个文件(默认名字是“cscope.in.out”、“cscope.po.out”)并且附加在正常的数据库上。
这会允许一个快速查询算法,这个算法能显著提高搜索效率,在针对大项目时。
-R Recurse subdirectories during search for source files.
在搜索源文件时,递归搜索子目录。
-sdir Look in dir for additional source files. This option is ignored
if source files are given on the command line.
在目录里搜索附加的源文件,当源文件在cmd被给定时,这个选项将被忽略。
-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.
只用第一个八个字符来匹配一个C语言符号。如果一个正则表达式大于八个字符,那么,在包含除了.号的指定字符 时,它将不匹配任何符号。
-U Check file time stamps. This option will update the time stamp
on the database even if no files have changed.
检查文件的时间戳。这个选项将会更新数据库里的时间戳,即使没有文件被改变。
-u Unconditionally build the cross-reference file (assume that all
files have changed).
无条件的构建交叉引用文件(假定所有文件被更改)。
-v Be more verbose in line-oriented mode. Output progress updates
during database building and searches.
基于行模式下更详细的输出。在数据库构建和搜索中,输出进度更新。
files A list of file names to operate on.
一个需要被搜索的文件名的列表。
The -I, -c, -k, -p, -q, and -T options can also be in the cscope.files
file.
-I, -c, -k, -p, -q, -T 这几个选项也能出现在cscope.files文件里。
Requesting the initial search
After the cross-reference is ready, cscope will display this menu:
请求最初的搜索
在交叉引用被准备完成后,cscope将会显示如下这个菜单:
Find this C symbol:
Find this function 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:
Press the <Up> or <Down> keys repeatedly to move to the desired input
field, type the text to search for, and then press the <Return> key.
按下<Up> 或者 <Down> 按键反复在以上的需要的字段中移动。按下return返回。
Issuing subsequent requests
If the search is successful, any of these single-character commands can
be used:
发动随后的请求
如果搜索是成功的,那么以下这些单字符命令就能被使用。
0-9a-zA-Z
Edit the file referenced by the given line number.
编辑那个被给定行号引用的文件。
<Space>
Display next set of matching lines.
显示匹配行的下一个集合。
<Tab> Alternate between the menu and the list of matching lines
在主菜单和匹配行结果中来回切换。
<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 the
matching line list.)
移动到前一个菜单项(如果光标在菜单里)或者移动到前一个匹配行(如果光标在匹配行列表)。
<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 the matching
line list.)
移动到下一个菜单项(如果光标在菜单)或者移动到下一个匹配行(如果光标在匹配行列表)。
+ Display next set of matching lines.
显示下一个匹配行集合。
- Display previous set of matching lines.
显示前一个匹配行集合。
^e Edit displayed files in order.
按顺序编辑被显示的文件。
> Write the displayed list of lines to a file.
把被显示行的列表写到一个文件里。
>> Append the displayed list of lines to a file.
追加被显示行的列表到一个文件里。
< Read lines from a file that is in symbol reference format (cre‐
ated by > or >>), just like the -F option.
从一个文件里读取行,这个文件时一个符号引用格式的(被> >>创建),就像 -F选项。
^ Filter all lines through a shell command and display the result‐
ing lines, replacing the lines that were already there.
过滤所有行,通过一个shell命令,并且显示结果行,替换已经在那的行。
| Pipe all lines to a shell command and display them without
changing them.
通过管道,将所有行导入一个shell命令,并且在显示它们的同时不会更改它们。
At any time these single-character commands can also be used:
在任何时候这些单字符命令也能被这么用:
<Return>
Move to next input field.
移动到下一个输入字段
^n Move to next input field.
移动到下一个输入字段
^p Move to previous input field.
移动到前一个输入字段
^y Search with the last text typed.
用最后文本指定的类型搜索。
^b Move to previous input field and search pattern.
移动到前一个输入字段并且搜索模式。
^f Move to next input field and searchpattern.
移动到下一个输入字段并且搜索模式。
^c Toggle ignore/use letter case when searching. (When ignoring
letter case, search for ``FILE'' will match ``File'' and
``file''.)
触发 忽略/使用 大小写敏感的开关,在搜索时。(当忽略大小写时,搜索“FILE”将会匹配
“File”和“file”)。
^r Rebuild the cross-reference.
重建交叉引用。
! Start an interactive shell (type ^d to return to cscope).
开始一个交互的shell(命令^d 会从cscope返回)。
^l Redraw the screen.
重画屏幕。
? Give help information about cscope commands.
获取关于cscope命令的帮助信息。
^d Exit cscope.
退出cscope。
NOTE: If the first character of the text to be searched for matches one
of the above commands, escape it by typing a (backslash) first.
注意:如果第一个用来被搜索的text的字符匹配任意以上一个命令,请首先用一个反斜杠定义来避免它。
Substituting new text for old text
将旧文本替换为新文本。
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:
在这个需要被改变的文本已经被类型化后,cscope将会为新文本做提示,并且将会
显示包含旧文本的行。用下面这些单字符命令选择需要被改变的行。
0-9a-zA-Z
Mark or unmark the line to be changed.
标记或取消标记需要被修改的行
* Mark or unmark all displayed lines to be changed.
标记或取消标记显示所有需要被修改的行
<Space>
Display next set of lines.
显示下一个行集合
+ Display next set of lines.
显示下一个行集合。
- Display previous set of lines.
显示上一个行集合
a Mark or unmark all lines to be changed.
标记或取消标记显示所有需要被修改的行
^d Change the marked lines and exit.
修改被标记的行并且退出。
<Esc> Exit without changing the marked lines.
退出并且不修改被标记的行。
! Start an interactive shell (type ^d to return to cscope).
开始一个交互Shell(命令 ^d 返回cscope)。
^l Redraw the screen.
重画屏幕。
? Give help information about cscope commands.
获取关于cscope命令的帮助信息。
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 <Tab>
key repeatedly. If you have <CLEAR>, <NEXT>, or <PREV> keys they
will act as the ^l, +, and - commands, respectively.
特别按键
如果你的终端有方向键,在VI里能工作的方向键,你能用它们在输入字段里走来走去。
上方向键被用来移动到前一个输入字段,代替反复使用TAB键。如果你有CLEAR、NEXT、或PREV
键,那它们将会分别担当^l, +, 和 - 命令。
Line-Oriented interface
The -l option lets you use cscope where a screen-oriented interface
would not be useful, for example, from another screen-oriented program.
基于行交互
-l选项让你这样使用cscope,在基于屏幕交互不可用的时候。比如,从其他基于屏幕
交互的程序。
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.
cscope将会用>>来提示,在它准备好的时候,准备好为一个开始在字段编号的输入行
立即跟随搜索模式。例如,“lmain” 会查找main函数的定义。
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.
如果你只想要一个单纯的搜索,用-L选项和-num模式选项来替代-l选项,并且你
不用获取>>提示。
For -l, cscope outputs the number of reference lines cscope: 2 lines
对于-l,cscope输出被引用行的数量:2行
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)
对于每个被找到的引用,cscope输出一个行,这个行由文件名,函数名,行号和
行文本组成,由空格隔开。
Note that the editor is not called to display a single reference,
unlike the screen-oriented interface.
注意那个编辑器不会被调用来显示一个单独的引用,不像基于屏幕的交互。
You can use the c command to toggle ignore/use letter case when search‐
ing. (When ignoring letter case, search for ``FILE'' will match
``File'' and ``file''.)
在搜索时,你能用c命令来开关忽略大小写的开关。(当选择忽略大小写时,搜索
“FILE”将会匹配“File”和“file”。)
You can use the r command to rebuild the database.
你能用r命令来重建数据库。
cscope will quit when it detects end-of-file, or when the first charac‐
ter of an input line is ``^d'' or ``q''.
当它检测到文件结尾时cscope将会退出,或者当第一个输入行的字符是“^d” 或“q”。
ENVIRONMENT VARIABLES
环境变量
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.
cscope编辑器
覆盖那个EDITOR和VIEWER变量。如果你希望在cscope里使用不同的编辑器,
通过指定这两个变量。
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 edi‐
tor 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''.
cscope行标记
你的编辑器的行标记的格式。默认的,cscope调用你的编辑器通过等同于
“editor +N file”这样的命令调用,当“N”时一个行号时,编辑器将会跳入。
这个格式被用在emacs和vi。如果你的编辑器需要做不同的事情,用这个变量
指定,用“%s”作为一个行号的占位符。除了:如果你的编辑器需要被这么调用,
“editor -#103 file”,将会到文件的103行,设置这个变量为“-#%s”。
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.
在文件后边的cscope行标记
如果你的编辑器需要被这样调用,把行号放在需要被编辑的文件名之后,
那么设置这个变量为“yes”。继续从《cscope行标记》这段的例子,如果
你的编辑器需要看``editor file -#number'',那就设置这个环境变量。
大多数标准编辑器(vi,emacs)的用户都不需要设置这个变量。
EDITOR Preferred editor, which defaults to vi.
编辑器 首选编辑器 它默认是vi。
HOME Home directory, which is automatically set at login.
HOME HOME目录,在登录时被自动设置。
INCLUDEDIRS
Colon-separated list of directories to search for #include
files.
包含目录
用冒号分割的一个目录列表,用来搜索#include 包含的文件。
SHELL Preferred shell, which defaults to sh.
首选shell,默认是sh。
SOURCEDIRS
Colon-separated list of directories to search for additional
source files.
源文件路径
用冒号分割的目录列表,用来搜索附加的源文件。
TERM Terminal type, which must be a screen terminal.
TERM 终端类型,比如时一个屏幕终端。
TERMINFO
Terminal information directory full path name. If your terminal
is not in the standard terminfo directory, see curses and ter‐
minfo for how to make your own terminal description.
终端信息目录的全路径名。如果你的终端不实在标准终端信息路径,可以
看 curses 和 terminfo 如果描述你自己的终端。
TMPDIR Temporary file directory, which defaults to /var/tmp.
临时目录 临时文件目录,默认是/var/tmp.
VIEWER Preferred file display program (such as less), which overrides
EDITOR (see above).
首选文件显示程序,覆盖编辑器。
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.
一个用冒号分割的目录列表,它们的每一个都用相通的目录结构。如果VPATH被
设置,cscope将会搜索这个目录指定的源文件。如果它没有被设置,cscope将
之后搜索当前目录。
FILES
cscope.files
Default files containing -I, -p, -q, and -T options and the list
of source files (overridden by the -i option).
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 cur‐
rent directory.
符号交叉引用文件(被-f选项重写),如果它不能在当前目录被创建,
那么它就会被放在home目录。
cscope.in.out
cscope.po.out
Default files containing the inverted index used for quick sym‐
bol 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.
包含用来快速查找系统符号(-q选项)的反向索引的默认文件。如果你
用-f选项来重命名交叉引用文件(那么它就不能时cscope.out),这些
反向索引文件将会被创建成,用你-f提供的名字再附加上.in和.po。例
如,如果你指明 -f xyz,那么这两个文件将会被命名为 xyz.in 和xyz.out。
INCDIR Standard directory for #include files (usually /usr/include).
#include 包含文件的标准目录(通常是 /usr/include)。
Notices
注意
cscope recognizes function definitions of the form:
fname blank ( args ) white arg_decs white {
cscope能辨认出的函数定义的格式:
where: fname is the function name
fname是函数的名字
blank is zero or more spaces, tabs, vtabs, form feeds or carriage
returns, not including newlines
是零或多个空格、tabs, vtabs,换行符或回车,不包含新行。
args is any string that does not contain a ``"'' or a newline
是任何不包含``"''或一个新行的字符串。
white is zero or more spaces, tabs, vtabs, form feeds, carriage
returns or newlines
是零或多个空格、tabs, vtabs,换行符或回车,新行。
arg_decs
are zero or more argument declarations (arg_decs may include
comments and white space)
是零或多个参数声明(arg_decs 有可能会包含注释和空格)
It is not necessary for a function declaration to start at the begin‐
ning 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.
一个函数声明开始在一行的开始不是必要的。返回类型有可能出现在函数名前面。
cscope将会一直辨认那个声明。脱离这种格式的函数定义将不会被cscope辨认。
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
这个搜索输出的列``Function'',查找被这个函数调用的函数:输入字段将只会
显示第一个在这个行被调用的函数,就像下面这个函数
e()
{
return (f() + g());
}
the display would be
Functions called by this function: e
File Function Line
a.c f 3 return(f() + g());
Occasionally, a function definition or call may not be recognized
because of braces inside #if statements. Similarly, the use of a vari‐
able may be incorrectly recognized as a definition.
偶尔的,一个函数定义或调用可能不会被辨认出来,因为括号里面的#if语句。同样
的,一个变量的使用也可能会被不正确的辨认为一个定义。
A typedef name preceding a preprocessor statement will be incorrectly
recognized as a global definition, for example,
一个 typedef 名字先于一个预处理语句将会被不正确的辨认为一个全局定义,例如,
LDFILE *
#if AR16WR
Preprocessor statements can also prevent the recognition of a global
definition, for example,
预处理语句也能阻止一个全局定义的辨认,例如,
char flag
#ifdef ALLOCATE_STORAGE
= -1
#endif
;
A function declaration inside a function is incorrectly recognized as a
function call, for example,
一个函数声明在一个函数里,会被不正确的辨认为一个函数调用,例如,
f()
{
void g();
}
is incorrectly recognized as a call to g.
被不正确的辨认为一个调用g函数。
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 recog‐
nize inline member function definitions in a structure. It also doesn't
expect the class keyword in a typedef , so it incorrectly recognizes X
as a definition in
cscope通过查找类关键字来辨认C++的类,但是不会辨认出一个结构也是一个类,
所以它不能辨认出定义在一个结构内的内联成员函数。它也不希望类关键字用
typedef,那么它会不正确的辨认出X 是一个定义。
typedef class X * Y;
It also doesn't recognize operator function definitions
它也不会辨认出操作符函数定义
Bool Feature::operator==(const Feature & other)
{
...
}
Nor does it recognize function definitions with a function pointer
argument
它也不能辨认一个函数指针参数。
ParseTable::Recognize(int startState, char *pattern,
int finishState, void (*FinalAction)(char *))
{
...
}
The Santa Cruz Operation January 2007 CSCOPE(1)