--- name: "gtags-cscope" section: "1" platform: "linux" package: "global" version: "6.7-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/gtags-cscope" --- # gtags-cscope(1) interactively examine a C program ## NAME gtags-cscope - interactively examine a C program ## SYNOPSIS **gtags-cscope** \[-abCdehilLvV\]\[-F file \]\[-012345678 *pattern*\]\[-p n\]\ ## DESCRIPTION **gtags-cscope** is an interactive, screen-oriented tool that allows the user to browse through source files for specified elements of code. **gtags-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, **gtags-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, it is updated incrementally, which makes rebuilding faster than the initial build. **gtags-cscope** is a tool which just borrows user interface of cscope; it is Global itself for the substance. ## OPTIONS Some command line arguments can only occur as the only argument in the execution of **gtags-cscope**. They cause the program to just print out some output and exit immediately: - **-h** View the long usage help display. - **-V** Print the version number of **gtags-cscope**. - **--help** Same as **-h** - **--version** Same as **-V** The following options can appear in any combination: - **-a** Print absolute path names. - **-b** Build the cross-reference only. - **-C** Ignore letter case when searching. - **-d** Do not update the cross-reference. - **-e** Suppress the ´^e´ command prompt between files. - **-F** *file* Read symbol reference lines from *file*. (A symbol reference file is created by \> and \>\>, and can also be read using the \< command, described under \`\`Issuing Subsequent Requests'', below.) - **-i** Ignore SIGINT signal in line-oriented mode. - **-L** Do a single search with line-oriented output when used with the -num pattern option. - **-l** Line-oriented interface. This option implies the **-d** option. - **-\[0-9\]** *pattern* Go to input field *num* (counting from 0) and find *pattern*. - **-p** *n* Display the last *n* file path components instead of the default (1). Use ´0´ to not display the file name at all. - **-v** Be more verbose in line-oriented mode. ## Requesting the initial search After the cross-reference is ready, **gtags-cscope** will display this menu: ``` Find this symbol: Find this global definition: Find functions called by this function (N/A): Find references of this function: Find this text string: Change this text string: Find this egrep pattern: Find this file: Find files #including this file: Find assignments to this symbol: ``` 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. - ^g Read lines from the result of the execution of [**global**(1)](/global/1.md). 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, a search for ´FILE´ will match ´File´ and ´file´.) - ^r Rebuild the cross-reference. - ! Start an interactive shell (type ´^d´ to return to **gtags-cscope**). - ^l Redraw the screen. - ? Give help information about **gtags-cscope** commands. - ^d Exit **gtags-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, **gtags-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 **gtags-cscope**). - ^l Redraw the screen. - ? Give help information about **gtags-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 **gtags-cscope** where a screen-oriented interface would not be useful, for example, from another screen-oriented program. **gtags-cscope** will prompt with ´\>\>´ when it is ready for an input line, which starts with the field number (counting from 0), immediately followed by the search pattern. For example, ´1main´ 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***,* **gtags-cscope** *outputs the number of reference lines:*\ *cscope: 2 lines* *For each reference found,* **gtags-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, a search for ´FILE´ will* *match ´File´ and ´file´.)* *You can use the ´r´ command to rebuild the database.* **gtags-cscope** *will quit when it detects end-of-file, or when the first* *character of an input line is ´^d´ or ´q´.* ## ENVIRONMENT *The following environment variables are of* **cscope** *origin.* - **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.* *Eg: 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.* - **SHELL** *Preferred shell, which defaults to* **sh***.* - **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 ´/tmp´.* - **VIEWER** *Preferred file display program (such as* **less***), which overrides* **EDITOR** *(see above).* *The following environment variables are of* **Global** *origin.* - **GTAGSCONF** *Configuration file.* - **GTAGSGLOBAL** *If this variable is set, ´$GTAGSGLOBAL´ is used as the name* *of* **global***(1). The default is* **global***.* - **GTAGSGTAGS** *If this variable is set, ´$GTAGSGTAGS´ is used as the name* *of* **gtags***(1). The default is* **gtags***.* - **GTAGSDBPATH** *The directory in which the tag files exist.* *This value is ignored when* **GTAGSROOT** *is not defined.* - **GTAGSLABEL** *Configuration label. The default is ´default´.* - **GTAGSLIBPATH** *If this variable is set, it is used as the path to search* *for library functions. If the specified tags is not* *found in the project,* **global** *also searches in these paths.* *Since only ´GTAGS´ is targeted in the retrieval, this variable is* *ignored when* **-r** *or* **-s** *is specified.* - **GTAGSROOT** *The root directory of the project.* - **MAKEOBJDIR** *If this variable is set, ´$MAKEOBJDIR´ is used as the name* *of BSD-style objdir. The default is ´obj´.* - **MAKEOBJDIRPREFIX** *If this variable is set, ´$MAKEOBJDIRPREFIX´ is used as the prefix* *of BSD-style objdir. The default is ´/usr/obj´.* ## FILES - *´GTAGS´* *Tag file for definitions.* - *´GRTAGS´* *Tag file for references.* - *´GPATH´* *Tag file for source files.* - *´GTAGSROOT´* *If environment variable* **GTAGSROOT** *is not set* *and file ´GTAGSROOT´ exists in the same directory as ´GTAGS´* *then* **global** *sets* **GTAGSROOT** *to the contents of the file.* - *´gtags.conf´, ´$HOME/.globalrc´* *Configuration data for GNU Global.* *See* **gtags.conf***(5).* ## SEE ALSO **gtags***(1),* **global***(1),* **htags***(1).* *GNU Global source code tag system*\ *(http://www.gnu.org/software/global/).* ## BUG *The function field of the display is almost \ since* **Global** *doesn't recognize it.* *´Find functions called by this function´ is not implemented.* ## AUTHOR *Joe Steffen (original author) and others.* ## HISTORY **Cscope** *was originally developed at Bell Labs in the early 1980s,* *and was released as free software under the BSD license in April 2000.* **Gtags-cscope** *is a derivative of* **cscope** *to use* **Global** *as the back-end.* *Its line-oriented interface was originally written in 2006, and was* *re-implemented in 2011 using* **cscope** *itself.*