vim+cscope阅读代码的利器

下载地址：
win32版本下载地址：
vim配置文件脚本示例：/cscope_maps.vim

目前就只能用这个鸟东西了，kscope搞不出来。。。。。

首先在目录下建立cscope索引文件

find -name '*.c' > cscope.file

cscope -Rbkq

这个命令会生成三个文件：cscope.out, cscope.in.out, cscope.po.out。
其中cscope.out是基本的符号索引，后两个文件是使用"-q"选项生成的，可以加快cscope的索引速度。
上面所用到的命令参数，含义如下：

-R: 在生成索引文件时，搜索子目录树中的代码
-b: 只生成索引文件，不进入cscope的界面
-k: 在生成索引文件时，不搜索/usr/include目录
-q: 生成cscope.in.out和cscope.po.out文件，加快cscope的索引速度

 

接下来，就可以在vim里读代码了。
不 过在使用过程中，发现无法找到C++的类、函数定义、调用关系。仔细阅读了cscope的手册后发现，原来cscope在产生索引文件时，只搜索类型为 C, lex和yacc的文件(后缀名为.c, .h, .l, .y)，C++的文件根本没有生成索引。不过按照手册上的说明，cscope支持c++和Java语言的文件。
于是按照cscope手册上提供的方法，先产生一个文件列表，然后让cscope为这个列表中的每个文件都生成索引。
为了方便使用，编写了下面的脚本来更新cscope和ctags的索引文件：

#!/bin/sh

find . -name "*.h" -o -name "*.c" -o -name "*.cc" > cscope.files
cscope -bkq -i cscope.files
ctags -R

这个脚本，首先使用find命令，查找当前目录及子目录中所有后缀名为".h", ".c"和".cc"的文件，并把查找结果重定向到文件cscope.files中。
然后cscope根据cscope.files中的所有文件，生成符号索引文件。
最后一条命令使用ctags命令，生成一个tags文件，在vim中执行":help tags"命令查询它的用法。它可以和cscope一起使用。

cs help

find 的选项

0或则S：查找本符号

1或则G：查找本定义

2或则D：查找本函数调用的函数

3或则C：查找调用本函数的函数

4或则T：查找本字符串

6或则E：查找本EGREP模式

7或则F：查找本文件

8或则I：查找包含本文件的文件

热后就可以在vim中使用cscope了，具体使用方法参考

//----------------------------------------------------------------------

---

cscope是什么？

cscope 是一个 C 语言的浏览工具，通过这个工具可以很方便地找到某个函数或变量的定义位置、被调用的位置等信息。目前支持 C 和 C++。cscope 自身带一个基于文本的用户界面，不过 gvim 提供了cscope接口，因此可以在 gvim 中调用 cscope，方便快捷地浏览源代码。

为什么要使用cscope？

假设我们在读一份很大的项目的源代码。我们也许会需要进行如下操作。

• 函数 foo() 调用了函数 bar()，想看看函数 bar() 的内容。
• 想知道 foo() 在什么地方被调用。
• 想知道一个结构类型的定义。

虽然在 Linux 下使用 grep 或者在 Windows 下使用文件查找功能也能找到想找的文件，但是效率太低了。有没有什么更为方便快捷的方法？

这就需要用到cscope。gvim结合cscope，可以很方便地完成以上的操作，只需简单地敲几下键盘即可跳转到想去的地方。

如何使用cscope？

下载

如果你使用的是Linux，那么恭喜你，很可能操作系统已经为你提供了cscope工具。使用下面的命令确认它是否存在：

cscope -V

如果cscope工具已经安装，上面的命令将显示cscope的版本号，类似于下面的结果：

cscope: version 16.0a

但是如果提示错误说找不到cscope命令，说明cscope尚未安装。你可以到网上去寻找cscope的RPM包。另外，我们可以从上下载到 cscope 的最新源代码。在Linux下你可以编译该源代码生成cscope的可执行文件。

如果你是Windows用户，就没有这么好的福气了，因为在Windows下编译程序并不是很简单的事情。好在已经有人为我们编译好了Windows版，可以从这里下载到：。

安装

安装很简单，只要将cscope的可执行文件放到PATH环境变量包含的目录中即可。推荐Windows用户将上面下载到的 cscope.exe 与 gvim 放在同一个目录下，如 C:\Program Files\Vim\gvim64 下，然后单击开始菜单选择运行，输入 cmd，启动命令行提示符程序，执行

cscope -V

如果能看到cscope的版本好则说明安装成功。

另外，为了方便地使用cscope，我们还需要下载cscope的键盘映射设置，这样就可以在gvim中简单地通过快捷键来使用 cscope，而不必敲复杂的命令了。键盘映射可以从这里下载：

将下载到的 cscope_maps.vim 放在gvim的插件目录里，如 C:\Program Files\Vim\vimfiles\plugin 中。Linux用户可以放在 $HOME/.vim/plugin 中。

建立符号数据库

我们假设我们要阅读的代码放在 D:\src\myproject 下。然后打开命令行，进入源代码所在的目录，为 cscope 建立搜索文件列表。在命令行中执行以下命令：

dir /s /b *.c *.h  > cscope.files

如果你的源代码是C++，则可以将 cpp 等扩展名也加入到上面的命令中。

dir /s /b *.c *.h *cpp *.hpp  > cscope.files

如果是Linux用户，则可以使用 find 命令实现同样的功能：

find $(pwd) -name "*.[ch]"

然后执行以下命令：

cscope -b

执行结束后你可以在当前目录下发现 cscope.out 文件，这就是 cscope 建立的符号数据库。

上面这个命令中，-b参数使得cscope不启动自带的用户界面，而仅仅建立符号数据库。

浏览源代码

使用 gvim 打开你的源代码目录中任意一个C程序文件。然后在gvim中执行如下命令：

:cscope add D:\src\myproject\cscope.out

由于在 gvim 中可以使用命令缩写，因此上面的命令可以写成：

:cs a D:\src\myproject\cscope.out

这样就打开了刚刚建立的符号数据库。通过下面的命令可以检查数据库连接的存在。

:cscope show

该命令可以缩写为

:cs s

现在将光标移动到源代码中的某个函数名上，依次按下一下组合键：

s

稍等片刻之后你会在屏幕下放看到如下的字样：

Cscope tag: display
   #   line  filename / context / line
   1    342  D:\src\myproject\src\global.h <>
             void display(void );
   2    616  D:\src\myproject\src\command.c <>
             display();
   3    138  D:\src\myproject\src\display.c <>
             display(void )
   4    385  D:\src\myproject\src\main.c <>
             display();
   5    652  D:\src\myproject\src\main.c <>
             display();
   6    663  D:\src\myproject\src\main.c <>
             display();
Enter nr or choice ( to abort):

这里显示出的就是整个工程中使用到了 display 这个标识符的位置。此时输入 4，回车，即可跳转到 main.c 的 385 行调用 display() 函数的地方进行浏览。浏览结束后按 或者 可以回到跳转前的位置。

然后将光标移动到源代码某个函数名上，迅速地依次安下面的组合键：

s

其中 按 Ctrl-2 即可输入。同样，屏幕上出现了一排结果，选择之后你会发现，跳转到的文件将在水平方向的新窗口中打开。

然后将光标移动到源代码某个函数名上，迅速地依次安下面的组合键：

s

选择之后你会发现，跳转到的文件将在垂直方向的新窗口中打开。

以上我们简单介绍了cscope的使用方法，其中我们只用到了一个 s 命令，即跟在 和 后面的 s 键。同样，我们可以使用以下的功能键实现不同的跳转功能。

• c: 查找该函数被调用的位置
• d: 查找该函数调用了哪些函数
• e: 查找指定的正规表达式
• f: 查找指定的文件
• g: 查找指定标识符的定义位置
• i: 查找该文件在哪些地方被包含
• s: 查找指定标识符的使用位置
• t: 查找指定的文本字符串

命令行使用说明

除了上述通过快捷键映射的方式使用cscope之外，也可以直接在gvim命令行中使用cscope。这样就可以随意定义查找字符串，而不必局限于源代码中已有的标识符。命令格式如下：

:cscope find  <关键字>

该命令可以缩写为

:cs f  <关键字>

一个比较实用的技巧是使用cscope打开文件。使用以下命令即可直接打开名为display.c的文件，而不必先切换到display.c所在的目录。

:cs f f display.c

cscope也支持正规表达式。如果记不清某个函数的名称，可以用下面的方式来找到该函数的定义位置。

:cs f g .*SetConfiguration.*

版权

Cscope虽然不是GPL版权，但是Cscope是开放源码的自由软件，使用Cscope无须支付任何费用。

参考

• Cscope官方主页,
• The Vim/Cscope tutorial,
• Cscope on Win32,
• Vim中关于 cscope 的帮助，使用 :help cscope 命令查看

其他

本文所需的cscope Win32版以及键盘映射配置等，在这里做了备份。万一文章中提到的URL无法下载时，请使用以下的下载链接。

• cscope 16.0a Win32版: cscope-16.0a-win32.7static.zip
• 键盘映射配置: cscope_maps.zip

//-------------------------------------------------------------------------
FreeBSD的ctags没有-R选项，迫使我尝试cscope，感觉比ctags强很多。

安装：
#cd /usr/ports/devel/cscope
#make install clean
#cd /usr/ports/editors/vim
#make WITH_GTK2=yes WITH_CSCOPE=yes install clean

配置：
.vimrc

" An example for a vimrc file.
"
" Maintainer: Bram Moolenaar
" Last change: 2002 Sep 19
"
" To use it, copy it to
" for Unix and OS/2: ~/.vimrc
" for Amiga: s:.vimrc
" for MS-DOS and Win32: $VIM\_vimrc
" for OpenVMS: sys$login:.vimrc

" When started as "evim", evim.vim will already have done these settings.
if v:progname =~? "evim"
  finish
endif

" Use Vim settings, rather then Vi settings (much
" This must be first, because it changes other options as a side effect.
set nocompatible


set autowrite
set nu
set cindent shiftwidth=4
set softtabstop=4

" allow backspacing over everything in insert mode
set backspace=indent,eol,start

set autoindent

if has("vms")
  set nobackup " do not keep a backup file, use versions instead
else
  set backup " keep a backup file
endif
set history=50 " keep 50 lines of command line history
set ruler " show the cursor position all the time
set showcmd " display incomplete commands
set incsearch " do incremental searching

" For Win32 GUI: remove 't' flag from 'guioptions': no tearoff menu entries
" let &guioptions = substitute(&guioptions, "t", "", "g")

" Don't use Ex mode, use Q for formatting
map Q gq

" This is an alternative that also works in block mode, but the deleted
" text is lost and it only works for putting the current register.
"vnoremap p "_dp

" Switch syntax highlighting on, when the terminal has colors
" Also switch on highlighting the last used search pattern.
if &t_Co > 2 || has("gui_running")
  syntax on
  set hlsearch
endif

" Only do this part when compiled with support for autocommands.
if has("autocmd")

  " Enable file type detection.
  " Use the default filetype settings, so that mail gets 'tw' set to 72,
  " 'cindent' is on in C files, etc.
  " Also load indent files, to automatically do language-dependent indenting.
  filetype plugin indent on

  " Put these in an autocmd group, so that we can delete them easily.
  augroup vimrcEx
  au!

  " For all text files set 'textwidth' to 78 characters.
  autocmd FileType text setlocal textwidth=78

  " When editing a file, always jump to the last known cursor position.
  " Don't do it when the position is invalid or when inside an event handler
  " (happens when dropping a file on gvim).
  autocmd BufReadPost *
    \ if line("'\"") > 0 && line("'\"") <= line("$") |
    \ exe "normal g`\"" |
    \ endif

  augroup END

else

  set autoindent " always set autoindenting on

endif " has("autocmd")

:colo evening

if has("cscope")
    set csprg=/usr/local/bin/cscope
    " use both cscope and ctag for 'ctrl-]', ':ta', and 'vim -t'
    set cscopetag
    set csto=0
    set cst
    set nocsverb
    " add any database in current directory
    if filereadable("cscope.out")
        cs add cscope.out
    " else add database pointed to by environment
    elseif $CSCOPE_DB != "       


        cs add $CSCOPE_DB
    endif
    set csverb
endif



使用:
在源码书根目录
#cscope -Rb
#vim xxx.c
然后就可以方便的ctrl+] ,ctrl + t 跳转来。

//------------------------------------------------------------------

The Vim/Cscope tutorial

Cscope is a very handy tool, but it's even better when you don't ever have to leave the comfort of your favorite editor (i.e. Vim) to use it. Fortunately, Cscope support has been built into Vim.

This tutorial introduces you both to Vim's built-in Cscope support, and to a set of maps that make searching more convenient.

It is assumed you know the basics of using a vi-style editor, but you don't need any particular knowledge about Vim (where Vim-specific features--like multiple windows--are used, a working knowledge of the features is briefly introduced). You also don't need to know anything about Cscope: the basics are introduced as we go along.

In a nutshell, Vim's Cscope support is very similar to Vim's features, in case you've used those. But since Cscope has more search types than ctags, there are a few differences.

This is a hands-on tutorial, so open up a shell, and follow these steps:

1. Get and install Cscope if you don't have it already on your machine. Ideally, you will also have Vim 6.x, but you can get most of the functionality with later versions of Vim 5 (vertical splits don't work, but horizontal splits will work if you modify the maps as described in the file's comments).

   Note: If your version of Vim wasn't compiled with '--enable-cscope', you will need to reconfigure and recompile Vim with that flag. Most Vim binaries that ship with Linux distributions have the Cscope plugin enabled.

2. Download the file, and arrange for it to be read by Vim at startup time. If you are using Vim 6.x, stick the file in your $HOME/.vim/plugin directory (or in any other 'plugin' subdirectory in your 'runtimepath'). If you are using Vim 5.x, you can either cut and paste the entire contents of the cscope_maps file into your $HOME/.vimrc file, or stick a "source cscope_maps.vim" line into your .vimrc file.
3. Go into a directory with some C code in it, and enter 'cscope -R' (the '-R' makes Cscope parse all subdirectories, not just the current directory). Since we aren't passing the '-b' flag (which tells Cscope to just build the database, then exit), you will also find yourself inside Cscope's curses-based GUI. Try a couple of searches (hint: you use the arrow keys to move around between search types, and 'tab' to switch between the search types and your search results). Hit the number at the far left of a search result, and Cscope will open Vim right to that location. (unless you've set your EDITOR environment variable to something besides Vim). Exit Vim, and you'll be right back in the Cscope GUI where you left off. Nifty.

   Alas, the Cscope interface has one big problem: you need to exit Vim each time you want to do a new search. That's where the Vim plugin comes in. Hit CTRL-D to exit Cscope.

4. Start up Vim. If you want, you can start it with a C symbol (ex: 'vim -t main'), and you should hop right to the definition of that symbol in your code.
5. Put the cursor over a C symbol that is used in several places in your program. Type "CTRL-\ s" (Control-backslash, then just 's') in quick succession, and you should see a menu at the bottom of your Vim window showing you all the uses of the symbol in the program. Select one of them and hit enter, and you'll jump to that use. As with ctags, you can hit "CTRL-t" to jump back to your original location before the search (and you can nest searches and CTRL-t will unwind them one at a time).

   Mnemonic: the '\' key is right next to the ']' key, which is used for ctags searches.

6. Try the same search, but this time via "CTRL-spacebar s". This time, your Vim window will split in two horizontally , and the Cscope search result will be put in the new window. [if you've never used multiple Vim windows before: move between windows via 'CTRL-W w' (or CTRL-W arrow key, or CTRL-W h/j/k/l for left/up/down/right), close a window via 'CTRL-W c' (or good old ':q'), make the current window the only one via 'CTRL-W o', split a window into two via 'CTRL-W s' (or 'CTRL-W v' for a vertical split), open a file in a new window via ':spl[it] filename']

   Mnemonic: there's now a big, spacebar-like bar across the middle of your screen separating your Vim windows.

   

7. Now try the same search via "CTRL-spacebar CTRL-spacebar s" (just hold down the CTRL key and tap the spacebar twice). If you have trouble hitting the keys fast enough for this to work, go into the cscope_maps.vim script and change Vim's timeout settings as described in the comments [actually, I generally recommend that you turn off Vim's timeouts]. This time your Vim window will be split vertically (note: this doesn't work with Vim 5.x, as vertical splits are new with Vim 6.0).
8. Up to now we've only been using the keystroke maps from 'cscope_maps.vim', which all do a search for the term that happens to be under your cursor in Vim. To do Cscope searches the old-fashioned way (using Vim's built-in Cscope support), enter ":cscope find symbol foo" (or, more tersely, ":cs f s foo"). To do the horizontal split version, use ":scscope" (or just ":scs") instead (Vim 6.x only). While it's easier to use the maps if the word you want to search for is under your cursor, the command line interface lets you go to any symbol you type in, so you'll definitely want to use it at times.
9. So far we've only been doing one kind of search: 's', for 'find all uses of symbol X'. Try doing one of Cscope's other searches by using a different letter: 'g' finds the global definition(s) of a symbol, 'c' finds all calls to a function, 'f' opens the filename under the cursor (note: since Cscope by default parses all C header files it finds in /usr/include, you can open up most standard include files with this). Those are the ones I use most frequently, but there are others (look in the cscope_maps.vim file for all of them, and/or read the Cscope man page).
10. Although Cscope was originally intended only for use with C code, it's actually a very flexible tool that works well with languages like C++ and Java. You can think of it as a generic 'grep' database, with the ability to recognize certain additional constructs like function calls and variable definitions. By default Cscope only parses C, lex, and yacc files (.c, .h, .l, .y) in the current directory (and subdirectories, if you pass the -R flag), and there's currently no way to change that list of file extensions (yes, we ought to change that). So instead you have to make a list of the files that you want to parse, and call it 'cscope.files' (you can call it anything you want if you invoke 'cscope -i foofile'). An easy (and very flexible) way to do this is via the trusty Unix 'find' command:

        find . -name '*.java' > cscope.files
    

    Now run 'cscope -b' to rebuild the database (the -b just builds the database without launching the Cscope GUI), and you'll be able to browse all the symbols in your Java files. Apparently there are folks out there using Cscope to browse and edit large volumes of documentation files, which shows how flexible Cscope's parser is.

    For larger projects, you may additionally need to use the -q flag, and/or use a more sophisticated 'find' command. See our for more info.

    

11. Try setting the $CSCOPE_DB environment variable to point to a Cscope database you create, so you won't always need to launch Vim in the same directory as the database. This is particularly useful for projects where code is split into multiple subdirectories. Note: for this to work, you should build the database with absolute pathnames: cd to /, and do

        find /my/project/dir -name '*.c' -o -name '*.h' > /foo/cscope.files
    

    Then run Cscope in the same directory as the cscope.files file (or use 'cscope -i /foo/cscope.files'), then set and export the $CSCOPE_DB variable, pointing it to the cscope.out file that results):

        cd /foo
        cscope -b
        CSCOPE_DB=/foo/cscope.out; export CSCOPE_DB   
    

    (The last command above is for Bourne/Korn/Bash shells: I've forgotten how to export variables in csh-based shells, since I avoid them like the plague).

    You should now be able to run 'vim -t foo' in any directory on your machine and have Vim jump right to the definition of 'foo'. I tend to write little shell scripts (that just define and export CSCOPE_DB) for all my different projects, which lets me switch between them with a simple 'source projectA' command.

    BUG: in versions of Cscope prior to 15.4, there is a silly bug that may cause Vim to freeze when you do this unless you call your database something other than the default 'cscope.out': use '-f foo' in your Cscope invocation to name your database 'foo.out' instead, and you'll be OK.

12. That's it! Use ":help cscope" (in Vim) and/or "man cscope" (from your shell) if you've got questions, and to learn the fine points.

//==========================

CSCOPE

---

NAME

cscope - interactively examine a C program

SYNOPSIS

cscope [ -bCcdehkLlqRTUuV ] [-Fsymfile] [-freffile] [-Iincdir] [-inamefile] [-numpattern] [-pn] [-sdir]

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, 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 invocation, 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.

OPTIONS

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.

-d

Do not update the cross-reference.

-e

Suppress the -e command prompt between files.

-F symfile

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.)

-f reffile

Use reffile as the cross-reference file name instead of the default cscope.out.

-h

View the long usage help display.

-I incdir

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.

-i namefile

Browse through all source files whose names are listed in namefile (file names separated by spaces, tabs, or new-lines) instead of the default (cscope.files). If this option is specified, cscope ignores any files appearing on the command line. The argument namefile can be set to ``-'' to accept a list of files from stdio. 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.

-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.

-L

Do a single search with line-oriented output when used with the -num pattern option.

-l

Line-oriented interface (see ``Line-Oriented Interface'' below).

-num pattern

Go to input field num (counting from 0) and find pattern.

-P path

Prepend 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.

-p n

Display the last n file path components instead of the default (1). Use 0 to not display the file name at all.

-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.

-R

Recurse subdirectories for source files.

-s dir

Look in dir for additional source files. This option is ignored if source files are given on the command line.

-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.

-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

Print on the first line of screen the version number of cscope.

The -I, -c, -k, -p, -q, and -T options can also be in the cscope.files file.

Requesting the initial search

After the cross-reference is ready, cscope will display this menu:

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 or keys repeatedly to move to the desired input field, type the text to search for, and then press the key.

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.

Display next set of matching lines.

Alternate between the menu and the list of matching lines

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.)

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 (created by > or >>), just like the -F option.

^

Filter all lines through a shell command and display the resulting lines, replacing the lines that were already there.

|

Pipe all lines to a shell command and display them without changing them.

At any time these single-character commands can also be used:

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 search pattern.

^c

Toggle ignore/use letter case when searching. (When ignoring letter case, search for ``FILE'' will match ``File'' and ``file''.)

^r

Rebuild the cross-reference.

!

Start an interactive shell (type ^d to return to cscope).

^l

Redraw the screen.

?

Give help information about cscope commands.

^d

Exit 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.

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:

0-9a-zA-Z

Mark or unmark the line to be changed.

*

Mark or unmark all displayed lines to be changed.

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.

Exit without changing the marked lines.

!

Start an interactive shell (type ^d to return to cscope).

^l

Redraw the screen.

?

Give help information about cscope commands.

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.

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.

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.

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.

For -l, cscope outputs the number of reference lines cscope: 2 lines

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)

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 searching. (When ignoring letter case, search for ``FILE'' will match ``File'' and ``file''.)

You can use the r command to rebuild the database.

cscope will quit when it detects end-of-file, or when the first character of an input line is ``^d'' or ``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_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''.

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.

EDITOR

Preferred editor, which defaults to vi.

HOME

Home directory, which is automatically set at login.

INCLUDEDIRS

Colon-separated list of directories to search for #include files.

SHELL

Preferred shell, which defaults to sh.

SOURCEDIRS

Colon-separated list of directories to search for additional source files.

TERM

Terminal type, which must be a screen terminal.

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.

TMPDIR

Temporary file directory, which defaults to /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.

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 current directory.

cscope.in.out

cscope.po.out

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.

INCDIR

Standard directory for #include files (usually /usr/include).

Notices

cscope recognizes function definitions of the form:

fname blank ( args ) white arg_decs white {

where:

fname is the function name

blank

is zero or more spaces or tabs, not including newlines

args

is any string that does not contain a ``"'' or a newline

white

is zero or more spaces, tabs, or newlines

arg_decs

are zero or more argument declarations (arg_decs may include comments and white space)

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.

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

 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 variable may be incorrectly recognized as a definition.

A typedef name preceding a preprocessor statement will be incorrectly recognized as a global definition, for example,

 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.

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 typedef , so it incorrectly recognizes X as a definition in

 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 *))
 {
   ...
 }

//-----------------------------------------------------------------------------------------------------------