if_cscop.txt ForVim version 9.1. Last change: 2024 May 11VIM REFERENCE MANUAL by Andy KahncscopeCscopeThis document explains how to use Vim'scscope interface.Cscopeisa tool like ctags, but think ofitasctags on steroids sinceitdoesa lot more than whatctags provides. In Vim, jumping toa result fromacscope queryis just like jumping to any tag;itis saved on thetag stackso that with the right keyboard mappings, you can jump back and forth betweenfunctionsas you normally would withtags.1.Cscope introductioncscope-intro2.Cscope related commandscscope-commands3.Cscopeoptionscscope-options4. How to usecscope in Vimcscope-howtouse5. Limitationscscope-limitations6. Suggested usagecscope-suggestions7. Availability& Informationcscope-infoThisis currently forUnix andWin32 only.==============================================================================1.Cscope introductioncscope-introThe following textis taken froma version of thecscope man page: -----Cscopeis an interactive screen-oriented tool that helps you: Learn howaC program works without endless flipping througha thick listing. Locate thesection of code to change to fixa bug without having to learn the entire program. Examine the effect ofa proposed change suchas addinga value to anenum variable. Verify thata change has been made in all source files suchas adding an argument to an existing function. Renamea global variable in all source files. Changea constant toa preprocessor symbol in selected lines of files. Itis designed to answer questions like: Whereis this symbol used? Whereisit defined? Where did this variable get its value? Whatis this global symbol's definition? Whereis this function in the source files? Whatfunctions call this function? Whatfunctions are called by this function? Where does the message "out ofspace" come from? Whereis this source file in the directory structure? What files include this header file?Cscope answers these questions froma symbol database thatit builds the first timeitis used on the source files. Ona subsequent call,cscope rebuilds the database only ifa source file has changed or thelist of source filesis different. When the databaseis rebuilt the data for the unchanged filesis copied from the old database, which makes rebuilding much faster than the initial build. -----Whencscopeis normally invoked, you will geta full-screen selectionscreen allowing you to makea query for one of the above questions.However, oncea matchis found to your query and you have entered yourtext editor to edit the source file containing match, you cannot simplyjump fromtag totagas you normally would with vi's Ctrl-] or:tagcommand.Vim'scscope interfaceis done by invokingcscope with its line-orientedinterface, and then parsing the output returned froma query. Theendresultis thatcscope query results become just like regular tags, soyou can jump to them just like youdo with normaltags (Ctrl-] or :tag)and thengo back by popping off thetagstack with Ctrl-T. (Pleasenotehowever, that you don't actually jump toacscopetag simply by doingCtrl-] or:tag without remapping these commands or setting an option.See the remaining sections on how thecscope interface works and forsuggested use.)==============================================================================2.Cscope related commandscscope-commands:cscope:cs:scs:scscopeE259E262E560E561Allcscope commands are accessed through suboptions to thecscope commands.:cscope or:csis the main command:scscope or:scs does the same and splits thewindow:lcscope or:lcs uses the location list, see:lcscopeThe available subcommands are:E563E564E566E568E622E623E625E626E609 add: Adda newcscope database/connection.USAGE:cs add{file|dir}[pre-path][flags][pre-path]is the pathname used with the-P command to cscope.[flags] are any additional flags you want to pass to cscope.EXAMPLES :cscope add /usr/local/cdb/cscope.out :cscope add /projects/vim/cscope.out /usr/local/vim :cscope add cscope.out /usr/local/vim -Ccscope-findcs-findE567 find: Query cscope. Allcscope queryoptions are available except option #5("Change thisgreppattern").USAGE:cs find{querytype}{name}{querytype} corresponds to the actualcscope line interface numbersas wellas default nvi commands:0 or s: Find thisC symbol1 org: Find this definition2 or d: Findfunctions called by this function3 or c: Findfunctions calling this function4 ort: Find this textstring6 or e: Find this egreppattern7 or f: Find this file8 or i: Find files #including this file9 or a: Find places where this symbolis assigneda valueFor all types, except 4 and 6, leading whitespace for{name}isremoved. For 4 and 6 thereis exactly onespace between{querytype}and{name}. Further whitespaceis included in{name}.EXAMPLES :cscope find c vim_free :cscope find 3 vim_free These two examples perform the same query:functions calling "vim_free". :cscope find t initOnce :cscope find t initOnce The first one searches for the text "initOnce", the second one for " initOnce". :cscope find 0 DEFAULT_TERM Executing this example on the source code for Vim 5.1 produces the following output:Cscope tag: DEFAULT_TERM# line filename/ context/ line 1 1009 vim-5.1-gtk/src/term.c <<GLOBAL>> #define DEFAULT_TERM (char_u *)"amiga" 2 1013 vim-5.1-gtk/src/term.c <<GLOBAL>> #define DEFAULT_TERM (char_u *)"win32" 3 1017 vim-5.1-gtk/src/term.c <<GLOBAL>> #define DEFAULT_TERM (char_u *)"pcterm" 4 1021 vim-5.1-gtk/src/term.c <<GLOBAL>> #define DEFAULT_TERM (char_u *)"ansi" 5 1025 vim-5.1-gtk/src/term.c <<GLOBAL>> #define DEFAULT_TERM (char_u *)"vt52" 6 1029 vim-5.1-gtk/src/term.c <<GLOBAL>> #define DEFAULT_TERM (char_u *)"os2ansi" 7 1033 vim-5.1-gtk/src/term.c <<GLOBAL>> #define DEFAULT_TERM (char_u *)"ansi" 8 1037 vim-5.1-gtk/src/term.c <<GLOBAL>># undef DEFAULT_TERM 9 1038 vim-5.1-gtk/src/term.c <<GLOBAL>> #define DEFAULT_TERM (char_u *)"beos-ansi" 10 1042 vim-5.1-gtk/src/term.c <<GLOBAL>> #define DEFAULT_TERM (char_u *)"mac-ansi" 11 1335 vim-5.1-gtk/src/term.c <<set_termname>> term= DEFAULT_TERM; 12 1459 vim-5.1-gtk/src/term.c <<set_termname>> if (STRCMP(term, DEFAULT_TERM)) 13 1826 vim-5.1-gtk/src/term.c <<termcapinit>> term= DEFAULT_TERM; 14 1833 vim-5.1-gtk/src/term.c <<termcapinit>> term= DEFAULT_TERM; 15 3635 vim-5.1-gtk/src/term.c <<update_tcap>>p= find_builtin_term(DEFAULT_TERM); Enter nr of choice (<CR> to abort): The output shows several pieces of information: 1. Thetag number (there are 15 in this example). 2. The line number where thetag occurs. 3. The filename where thetag occurs. 4. The context of thetag (e.g., global, or the function name). 5. The line from the file itself.help: Showa brief synopsis. USAGE:cshelpE261 kill: Killacscope connection (or kill allcscope connections). USAGE:cs kill{num|partial_name} To killacscope connection, the connection number orapartial namemust be specified. Thepartial nameis simply any part of the pathname of thecscope database. Killacscope connection using thepartial name with caution! If the specified connection numberis -1, then _ALL_cscope connections will be killed. reset: Reinit allcscope connections. USAGE:cs reset show: Showcscope connections. USAGE:cs show:lcscope:lcsThis commandis sameas the ":cscope" command, except when the'cscopequickfix' optionis set, the locationlist for the currentwindowisused instead of thequickfixlist to show thecscope results.:cstagE257E562If you usecscopeas wellas ctags,:cstag allows you to search one orthe other before makinga jump. For example, you can choose to firstsearch yourcscope database(s) fora match, and if oneis not found, thenyourtags file(s) will be searched. The order in which this happensis determined by the value ofcsto. Seecscope-options for moredetails.:cstag performs the equivalent of ":cs findg" on the identifier whensearching through thecscope database(s).:cstag performs the equivalent of:tjump on the identifier when searchingthrough yourtags file(s).==============================================================================3.Cscopeoptionscscope-optionsUse the:set command to set allcscope options. Ideally, you woulddothis in one of yourstartup files (e.g., .vimrc). Somecscope relatedvariables are only valid within.vimrc. Setting them after vim hasstarted will have no effect!cscopeprgcsprg'cscopeprg'specifies the command to execute cscope. The defaultis"cscope". For example::set csprg=/usr/local/bin/cscopecscopequickfixcsqfE469{not available when compiled without the |+quickfix| feature}'cscopequickfix'specifies whether to usequickfixwindow to showcscoperesults. Thisisalist of comma-separated values. Each item consists ofcscope-find command (s,g, d, c, t, e, f,i ora) and flag (+,- or 0).'+' indicates that resultsmust be appended toquickfix window,'-' implies previous results clearance, '0' or command absence- don't usequickfix. Searchis performed from start until first command occurrence.The default valueis "" (don't usequickfix anyway). The following valueseems to be useful::set cscopequickfix=s-,c-,d-,i-,t-,e-,a-cscopetagcstIf'cscopetag'is set, the commands ":tag" andCTRL-]as wellas "vim-t"will always use:cstag instead of the default:tag behavior. Effectively,by setting'cst', you will always search yourcscope databasesas wellasyourtag files. The defaultis off. Examples::set cst:set nocstcscoperelativecsreIf'cscoperelative'is set, then in absence ofa prefix given tocscope(prefixis the argument of-P option of cscope), basename of cscope.outlocation (usually the project root directory) will be usedas the prefixto construct an absolute path. The defaultis off.Note: This optionisonly effective whencscope (cscopeprg)is initialized withouta prefixpath (-P). Examples::set csre:set nocsrecscopetagordercstoThe value of'csto' determines the order in which:cstag performsa search.If'csto'is set to zero,cscope database(s) are searched first, followedbytag file(s) ifcscope did not return any matches. If'csto'is set toone,tag file(s) are searched beforecscope database(s). The defaultis zero.Examples::set csto=0:set csto=1cscopeverbosecsverbIf'cscopeverbose'is not set (the default),messages will not be printedindicating success or failure when addingacscope database. Ideally, youshould reset this option in your.vimrc before adding anycscope databases,and after adding them, set it. From then on, when you add more databaseswithin Vim, you will geta (hopefully) useful message should the database failto be added. Examples::set csverb:set nocsverbcscopepathcompcspcThe value of'cspc' determines how many components ofa file's path todisplay. With the default value of zero the entire path will be displayed.The value one will display only the filename with no path. Other valuesdisplay that many components. For example::set cspc=3will display the last 3 components of the file's path, including the filename itself.==============================================================================4. How to usecscope in Vimcscope-howtouseThe first thing you need todois to buildacscope database for yoursource files. For the most basic case, simplydo "cscope-b". Pleaserefer to thecscope man page for more details.Assuming you haveacscope database, you need to "add" the database to Vim.This establishesacscope "connection" and makesit available for Vim to use.You cando this in your.vimrc file, or you candoit manually afterstartingvim. For example, to add thecscope database "cscope.out", you would do::cs add cscope.outYou can double-check the result of this by executing ":cs show". This willproduce output which looks like this:# pid database name prepend path0 28806 cscope.out<none>Note:Because of the Microsoft RTL limitations,Win32 version shows0 insteadof the real pid.Onceacscope connectionis established, you can make queries tocscope andthe results will be printed to you. Queries are made using the command":cs find". For example::cs findg ALIGN_SIZEThis can geta little cumbersome since one ends up doinga significantamount of typing. Fortunately, there are ways around this bymappingshortcut keys. Seecscope-suggestions for suggested usage.If the results return only one match, you will automatically be taken to it.If thereis more than one match, you will be givena selection screen to pickthe match you want togo to. After you have jumped to the new location,simply hit Ctrl-T to get back to the previous one.==============================================================================5. Limitationscscope-limitationsCscope support for Vimis only available on systems that support these foursystem calls: fork(), pipe(), execl(), waitpid(). This meansitis mostlylimited toUnix systems.AdditionallyCscope support works for Win32. For more information andacscope version forWin32 see (link seems dead):http://iamphet.nm.ru/cscope/index.htmlThe DJGPP-built version fromhttp://cscope.sourceforge.netis known to notwork with Vim.Hard-coded limitation: doinga:tjump when:cstag searches thetag filesis not configurable (e.g., you can'tdoa tselect instead).==============================================================================6. Suggested usagecscope-suggestionsPut these entries in your.vimrc (adjust the pathname accordingly to yoursetup):if has("cscope")set csprg=/usr/local/bin/cscopeset csto=0set cstset nocsverb" add any database in current directoryif filereadable("cscope.out") cs add cscope.out" else add database pointed to by environmentelseif $CSCOPE_DB != "" cs add $CSCOPE_DBendifset csverbendifBy setting'cscopetag', we have effectively replaced all instances of the:tagcommand with :cstag. This includes :tag, Ctrl-], and "vim-t". In doingthis, the regulartag command not only searches yourctags generatedtagfiles, but yourcscope databasesas well.Some users may want to keep the regulartag behavior and havea differentshortcut to access :cstag. For example, one could map Ctrl-_ (underscore)to:cstag with the following command:map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR>A couple of very commonly usedcscope queries (using ":cs find")is tofind allfunctions callinga certain function and to find all occurrencesofa particularC symbol. Todo this, you can use these mappingsas anexample:map g<C-]> :cs find 3 <C-R>=expand("<cword>")<CR><CR>map g<C-\> :cs find 0 <C-R>=expand("<cword>")<CR><CR>These mappings for Ctrl-] (right bracket) and Ctrl-\ (backslash) allow you toplace your cursor over the function name orC symbol and quickly querycscopefor any matches.Or you may use the following scheme, inspired by Vim/Cscope tutorial fromCscope Home Page (http://cscope.sourceforge.net/):nmap <C-_>s :cs find s <C-R>=expand("<cword>")<CR><CR>nmap <C-_>g :cs find g <C-R>=expand("<cword>")<CR><CR>nmap <C-_>c :cs find c <C-R>=expand("<cword>")<CR><CR>nmap <C-_>t :cs find t <C-R>=expand("<cword>")<CR><CR>nmap <C-_>e :cs find e <C-R>=expand("<cword>")<CR><CR>nmap <C-_>f :cs find f <C-R>=expand("<cfile>")<CR><CR>nmap <C-_>i :cs find i ^<C-R>=expand("<cfile>")<CR>$<CR>nmap <C-_>d :cs find d <C-R>=expand("<cword>")<CR><CR>nmap <C-_>a :cs find a <C-R>=expand("<cword>")<CR><CR>" Using 'CTRL-spacebar' then a search type makes the vim window" split horizontally, with search result displayed in" the new window.nmap <C-Space>s :scs find s <C-R>=expand("<cword>")<CR><CR>nmap <C-Space>g :scs find g <C-R>=expand("<cword>")<CR><CR>nmap <C-Space>c :scs find c <C-R>=expand("<cword>")<CR><CR>nmap <C-Space>t :scs find t <C-R>=expand("<cword>")<CR><CR>nmap <C-Space>e :scs find e <C-R>=expand("<cword>")<CR><CR>nmap <C-Space>f :scs find f <C-R>=expand("<cfile>")<CR><CR>nmap <C-Space>i :scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>nmap <C-Space>d :scs find d <C-R>=expand("<cword>")<CR><CR>nmap <C-Space>a :scs find a <C-R>=expand("<cword>")<CR><CR>" Hitting CTRL-space *twice* before the search type does a vertical" split instead of a horizontal onenmap <C-Space><C-Space>s\:vert scs find s <C-R>=expand("<cword>")<CR><CR>nmap <C-Space><C-Space>g\:vert scs find g <C-R>=expand("<cword>")<CR><CR>nmap <C-Space><C-Space>c\:vert scs find c <C-R>=expand("<cword>")<CR><CR>nmap <C-Space><C-Space>t\:vert scs find t <C-R>=expand("<cword>")<CR><CR>nmap <C-Space><C-Space>e\:vert scs find e <C-R>=expand("<cword>")<CR><CR>nmap <C-Space><C-Space>i\:vert scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>nmap <C-Space><C-Space>d\:vert scs find d <C-R>=expand("<cword>")<CR><CR>nmap <C-Space><C-Space>a\:vert scs find a <C-R>=expand("<cword>")<CR><CR>==============================================================================7.Cscope availability and informationcscope-infoIf youdo not already havecscope (it did not come with your compilerlicense or OS distribution), then you candownloadit for free from:http://cscope.sourceforge.net/Thisis released by SCO under the BSD license.In Solaris 2.x, if you have theC compiler license, you will also havecscope. Both are usually located under /opt/SUNWspro/binThereis source to an older version ofacscope clone (called "cs") availableon the net. Due tovarious reasons, thisis not supported with Vim.Thecscope interface/support for Vim was originally written byAndy Kahn <ackahn@netapp.com>. The original structure (as wellasa tinybit of code) was adapted from thecscope interface in nvi.cscope-win32Foracscope version forWin32 see (seems abandoned):https://code.google.com/archive/p/cscope-win32/Win32 support was added by Sergey Khorev <sergey.khorev@gmail.com>. Contacthim if you have Win32-specific issues. vim:tw=78:ts=8:noet:ft=help:norl: