Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GTAGS-CSCOPE(1)		    General Commands Manual	       GTAGS-CSCOPE(1)

NAME
       gtags-cscope - interactively examine a C	program

SYNOPSIS
       gtags-cscope [-bCdehLlVv][-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	< com-
	      mand, 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  <Up>	or <Down> keys repeatedly to move to the desired input
       field, type the text to search for, and then press the <Return> 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.

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

       ^      Filter all lines through a shell command and display the result-
	      ing 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).

       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 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 com-
       mands:

       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	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 <Tab>
	      key repeatedly. If you have <CLEAR>, <NEXT>, or <PREV> 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	inter-
       face 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  fol-
       lowed  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 spa-
       ces.  For example:
       main.c main 161 main(argc, argv)

       Note  that  the editor is not called to display a single	reference, un-
       like 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 VARIABLES
       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 vari-
	      able.  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  ter-
	      minfo 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  ig-
	      nored 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 pre-
	      fix 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 'GTAGS-
	      ROOT' 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	<unknown> 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.

GNU Project			  March	2011		       GTAGS-CSCOPE(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | Requesting the initial search | Issuing subsequent requests | Line-Oriented interface | ENVIRONMENT VARIABLES | FILES | SEE ALSO | BUG | AUTHOR | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gtags-cscope&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help