"Fossies" - the Fresh Open Source Software Archive

Member "global-6.6.5/global/manual.in" (3 Sep 2020, 16150 Bytes) of package /linux/misc/global-6.6.5.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "manual.in": 6.6.4_vs_6.6.5.

    1 #
    2 # Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2006,
    3 #	2008, 2009, 2011, 2012, 2013, 2014, 2015
    4 #	Tama Communications Corporation
    5 #
    6 # This file is part of GNU GLOBAL.
    7 #
    8 # This program is free software: you can redistribute it and/or modify
    9 # it under the terms of the GNU General Public License as published by
   10 # the Free Software Foundation, either version 3 of the License, or
   11 # (at your option) any later version.
   12 # 
   13 # This program is distributed in the hope that it will be useful,
   14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
   15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   16 # GNU General Public License for more details.
   17 # 
   18 # You should have received a copy of the GNU General Public License
   19 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
   20 #
   21 # This file is converted to the following files:
   22 #	o command source file (for usage and help).
   23 #	o man format reference manual.
   24 #	o texinfo format reference manual.
   25 #
   26 @HEADER	GLOBAL,1,May 2015,GNU Project
   27 @NAME	global - print locations of given symbols
   28 @SYNOPSIS
   29 	@name{global} [-adEFGilMnNqrstTvx][-S dir][-e] @arg{pattern}
   30 	@name{global} -c[dFiIMoOPrsT] @arg{prefix}
   31 	@name{global} -f[adlnqrstvx][-L file-list][-S dir] @arg{files}
   32 	@name{global} -g[aEGilMnoOqtvVx][-L file-list][-S dir][-e] @arg{pattern} [@arg{files}]
   33 	@name{global} -I[ailMnqtvx][-S dir][-e] @arg{pattern}
   34 	@name{global} -P[aEGilMnoOqtvVx][-S dir][-e] @arg{pattern}
   35 	@name{global} -p[qrv]
   36 	@name{global} -u[qv]
   37 @DESCRIPTION
   38 	@name{Global} finds locations of given symbols
   39 	in C, Yacc, Java, PHP and assembly source files,
   40 	and prints the path name, line number and line image of the locations.
   41 	@name{Global} can locate not only definitions but also references
   42 	and other symbols.
   43 
   44 	@name{Global} can treat a source tree, that is, a directory that has
   45 	sub-directories and source files, as a project.
   46 	In advance of using this command, you must execute @xref{gtags,1}
   47 	at the root directory of the project which you want to investigate
   48 	to make tag files.
   49 	Then you can use @name{global} command anywhere in the project.
   50 	You need not specify where the tag file is.
   51 	Instead, @name{global} locates it by itself.
   52 
   53 	You can specify a regular expression for @arg{pattern}.
   54 	@name{Global} understands two different versions of regular expression
   55 	syntax: basic and extended (default).
   56 @COMMANDS
   57 	The following commands are available:
   58 
   59 	@begin_itemize
   60 	@item{<no command> @arg{pattern}}
   61 		No command means tag search command.
   62 		Print tags which match to @arg{pattern}.
   63 		By default, print definition tags.
   64 	@item{@option{-c}, @option{--completion} [@arg{prefix}]}
   65 		Print symbols which start with @arg{prefix}.
   66 		If @arg{prefix} is not given, print all symbols.
   67 	@item{@option{-f}, @option{--file} @arg{files}}
   68 		Print all tags in the @arg{files}.
   69 		This command implies the @option{-x} option.
   70 	@item{@option{-g}, @option{--grep} @arg{pattern} [@arg{files}]}
   71 		Print all lines which match to the @arg{pattern}.
   72 		If @arg{files} are given, this command searches in those files.
   73 	@item{@option{--help}}
   74 		Print a usage message.
   75 	@item{@option{-I}, @option{--idutils} @arg{pattern}}
   76 		Print all lines which match to @arg{pattern}.
   77 		This function uses @xref{idutils,1} as a search engine.
   78 		To use this command, you need to install @xref{idutils,1}
   79 		in your system and execute @xref{gtags,1} with the @option{-I} option.
   80 	@item{@option{-P}, @option{--path} [@arg{pattern}]}
   81 		Print path names which match to @arg{pattern}.
   82 		If no pattern is given, print all paths in the project.
   83 	@item{@option{-p}, @option{--print-dbpath}}
   84 		Print location of @file{GTAGS}.
   85 	@item{@option{--print} @arg{name}}
   86 		Print location of @arg{name}, which may be one of:
   87 		@val{root}, @val{dbpath} or @val{conf}.
   88 		@val{root} means project's root directory. @val{dbpath} means a directory
   89 		where tag databases exist. @val{conf} means configuration file.
   90 	@item{@option{-u}, @option{--update}}
   91 		Update tag files incrementally.
   92 		This command internally invokes @xref{gtags,1}.
   93 		You can execute this command anywhere in the project,
   94 		differing from @xref{gtags,1}.
   95 	@item{@option{--version}}
   96 		Show version number.
   97 	@end_itemize
   98 @OPTIONS
   99 	The following options are available:
  100 
  101 	@begin_itemize
  102 	@item{@option{-a}, @option{--absolute}}
  103 		Print absolute path names. By default, print relative path names.
  104 	@item{@option{--color} @arg{when}}
  105 		Use color to highlight the pattern within the line; @arg{when} may be one of:
  106 		@arg{never}, @arg{always} or @arg{auto} (default).
  107 		The default color is bold red text on current background; the environment
  108 		variable @var{GREP_COLORS} (only @var{mt} and @var{ms} are effective at present)
  109 		or @var{GREP_COLOR} defines it.
  110 		This option is effective to the following commands:
  111 		<no command>, -f, -g, -I, -P.
  112 	@item{@option{-C}, @option{--directory} @arg{dir}}
  113 		Change the directory before doing all the work including parameter analysis.
  114 	@item{@option{-d}, @option{--definition}}
  115 		Print locations of definitions.
  116 	@item{@option{-e}, @option{--regexp} @arg{pattern}}
  117 		Use @arg{pattern} as the pattern; useful to protect patterns starting with @samp{-}.
  118 	@item{@option{-E}, @option{--extended-regexp}}
  119 		Interpret @arg{pattern} as a extended regular expression.
  120 		This is the default.
  121 	@item{@option{--encode-path} @arg{chars}}
  122 		Convert path characters in @arg{chars} into a @samp{%} symbol, followed by the
  123 		two-digit hexadecimal representation of the character.
  124 		A blank will be converted to @samp{%20}.
  125 	@item{@option{-F}, @option{--first-match}}
  126 		End the search without going through all the tag files listed in
  127 		@var{GTAGSLIBPATH} when tags are found in a tag file. This is the default.
  128 	@item{@option{--from-here} @arg{context}}
  129 		Decide tag type by @arg{context}. Its syntax should be @samp{lineno:path}.
  130 		If the context is a definition of the pattern then use @option{-r}, else if
  131 		there is at least one definition of the pattern then use @option{-d},
  132 		else use @option{-s}.
  133 		If this option is specified then @option{-d}, @option{-r} and @option{-s}
  134 		on the command line are ignored.
  135 		Regular expression is not allowed for @arg{pattern}.
  136 		This option assumes use in conversational environments such as
  137 		editors and IDEs.
  138 	@item{@option{-G}, @option{--basic-regexp}}
  139 		Interpret @arg{pattern} as a basic regular expression.
  140 		The default is an extended regular expression.
  141 	@item{@option{--gtagsconf} @arg{file}}
  142 		Set environment variable @var{GTAGSCONF} to @arg{file}.
  143 	@item{@option{--gtagslabel} @arg{label}}
  144 		Set environment variable @var{GTAGSLABEL} to @arg{label}.
  145 	@item{@option{-i}, @option{--ignore-case}}
  146 		Ignore case distinctions in the pattern.
  147 	@item{@option{-L}, @option{--file-list} @arg{file}}
  148 		Obtain files from @arg{file} in addition to the arguments.
  149 		The argument @arg{file} can be set to '-' to accept a list of files
  150 		from the standard input. File names must be separated by newline.
  151 	@item{@option{-l}, @option{--local}}
  152 		Print only tags which exist under the current directory.
  153 	@item{@option{--literal}}
  154 		Execute literal search instead of regular expression search.
  155 		This option works with the tag search command, @option{-g} command, 
  156 		@option{-P} command and @option{-I} command.
  157 	@item{@option{-M}, @option{--match-case}}
  158 		Search is case-sensitive. This is the default.
  159 	@item{@option{--match-part @arg{part}}}
  160 		Specify how path name completion should match, where @arg{part} is one of:
  161 		@val{first}, @val{last} or @val{all} (default).
  162 		This option is valid only with the @option{-c} command in conjunction with @option{-P}.
  163 	@item{@option{-n}, @option{--nofilter}}
  164 		Suppress sort filter and path conversion filter.
  165 	@item{@option{-N}, @option{--nearness}[=@arg{start}]}
  166 		Use Nearness sort method (sorting by closest from @arg{start}) for the output.
  167 		By default, alphabetical sort method is used.
  168 		This option is effective for the tag search command, @option{-P} command
  169 		and @option{-g} command. As an exception, @option{-g} command ignores this
  170 		option when files are specified by arguments.
  171 		The nearness is defined by how many parent directories to go up to reach
  172 		the target. The result of nearness sort is concatenation of the following
  173 		([0]-[n]) in this order. The default of @arg{start} is the current directory.
  174 		@begin_verbatim
  175 		[0] If the start is a file, output of local search in the file.
  176 		[1] Output of local search in the start directory except for [0].
  177 		[2] Output of local search in the parent directory except for [0]-[1].
  178 		[3] Output of local search in the grandparent directory except for [0]-[2].
  179 		... (repeat until the project root directory)
  180 		[n] Output of local search in the project root directory except for [0]-[n-1].
  181 		@end_verbatim
  182 		In each directory, they are sorted by alphabetical order.
  183 	@item{@option{-O}, @option{--only-other}}
  184 		Treat only text files other than source code, like @file{README}.
  185 		This option is valid only with the @option{-g} or @option{-P} command.
  186 		This option overrides the @option{-o} option.
  187 	@item{@option{-o}, @option{--other}}
  188 		Treat not only source files but also text files other than source code,
  189 		like @file{README}.
  190 		This option is valid only with the @option{-g} or @option{-P} command.
  191 	@item{@option{--path-style} @arg{format}}
  192 		Print path names using @arg{format}, which may be one of:
  193 		@val{relative}, @val{absolute}, @val{shorter}, @val{abslib} or @val{through}.
  194 		@val{relative} means relative path. @val{absolute} means absolute path.
  195 		@val{shorter} means the shorter one of relative and absolute path.
  196 		@val{abslib} means absolute path for libraries (GTAGSLIBPATH) and relative path
  197 		for the rest.
  198 		@val{through} means the relative path from the project root directory
  199 		(internal format of GPATH).
  200 		The default is @val{relative}.
  201 		The @option{--path-style} option is given more priority than the @option{-a} option.
  202 	@item{@option{--print0}}
  203 		Print each record followed by a null character instead of a newline.
  204 	@item{@option{-q}, @option{--quiet}}
  205 		Quiet mode.
  206 	@item{@option{-r}, @option{--reference}, @option{--rootdir}}
  207 		Print reference tags.
  208 		Reference means the reference to a symbol which has definitions.
  209 		With the @option{-p} option, print the root directory of the project.
  210 	@item{@option{--result} @arg{format}}
  211 		Print out using @arg{format}, which may be one of:
  212 		@val{path} (default), @val{ctags}, @val{ctags-x}, @val{grep} or @val{cscope}.
  213 		The @option{--result=ctags} and @option{--result=ctags-x} options are
  214 		equivalent to the @option{-t} and @option{-x} options respectively.
  215 		The @option{--result} option is given more priority than the @option{-t} and @option{-x} options.
  216 	@item{@option{--single-update} @arg{file}}
  217 		Update tag files using @xref{gtags,1} with the @option{--single-update} option.
  218 		It is considered that @arg{file} was added, updated or deleted,
  219 		and there is no change in other files.
  220                 This option implies the @option{-u} option.
  221 	@item{@option{-s}, @option{--symbol}}
  222 		Print other symbol tags.
  223 		Other symbol means the reference to a symbol which has no definition.
  224 	@item{@option{-S}, @option{--scope} @arg{dir}}
  225 		Print only tags which exist under @arg{dir} directory.
  226 		It is similar to the @option{-l} option, but you need not change directory.
  227 	@item{@option{-T}, @option{--through}}
  228 		Go through all the tag files listed in @var{GTAGSLIBPATH}.
  229 		By default, stop searching when tag is found.
  230 		This option is ignored when either @option{-s}, @option{-r}
  231 		or @option{-l} option is specified.
  232 	@item{@option{-t}, @option{--tags}}
  233 		Use standard ctags format.
  234 	@item{@option{-V}, @option{--invert-match}}
  235 		Invert the sense of matching, to select non-matching lines.
  236 		This option is valid only with the @option{-g} or @option{-P} commands.
  237 	@item{@option{-v}, @option{--verbose}}
  238 		Verbose mode.
  239 	@item{@option{-x}, @option{--cxref}}
  240 		Use standard ctags cxref (with @option{-x}) format.
  241 	@end_itemize
  242 @EXAMPLES
  243 	@begin_verbatim
  244 	$ ls -F
  245 	Makefile      src/    lib/
  246 	$ gtags
  247 	$ ls G*
  248 	GPATH   GRTAGS  GTAGS
  249 	$ global main
  250 	src/main.c
  251 	$ (cd src; global main)
  252 	main.c
  253 	$ global -x main
  254 	main              10 src/main.c  main (argc, argv) {
  255 	$ global -f src/main.c
  256 	main              10 src/main.c  main (argc, argv) {
  257 	func1             55 src/main.c  func1() {
  258 	func2             72 src/main.c  func2() {
  259 	func3            120 src/main.c  func3() {
  260 	$ global -x '^[sg]et'
  261 	set_num           20 lib/util.c  set_num(values) {
  262 	get_num           30 lib/util.c  get_num() {
  263 	$ global -rx set_num
  264 	set_num          113 src/op.c            set_num(32);
  265 	set_num          225 src/opop.c               if (set_num(0) > 0) {
  266 	$ global strlen
  267 	$ (cd /usr/src/sys; gtags)
  268 	$ export GTAGSLIBPATH=/usr/src/sys
  269 	$ global -a strlen
  270 	/usr/src/sys/libkern/strlen.c
  271 	$ (cd /usr/src/lib; gtags)
  272 	$ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
  273 	$ global -a strlen
  274 	/usr/src/lib/libc/string/strlen.c
  275 	@end_verbatim
  276 @FILES
  277 	@begin_itemize
  278 	@item{@file{GTAGS}}
  279 		Tag file for definitions.
  280 	@item{@file{GRTAGS}}
  281 		Tag file for references.
  282 	@item{@file{GPATH}}
  283 		Tag file for source files.
  284 	@item{@file{GTAGSROOT}}
  285 		If environment variable @var{GTAGSROOT} is not set
  286 		and file @file{GTAGSROOT} exists in the same directory as @file{GTAGS}
  287 		then @name{global} sets @var{GTAGSROOT} to the contents of the file.
  288 	@item{@file{gtags.conf}, @file{$HOME/.globalrc}}
  289 		Configuration data for GNU GLOBAL.
  290 		See @xref{gtags.conf,5}.
  291 	@end_itemize
  292 @ENVIRONMENT
  293 	The following environment variables affect the execution of @name{global}:
  294 
  295 	@begin_itemize
  296 	@item{@var{GREP_COLOR}}
  297 		The color to use for @option{--color}; @var{GREP_COLORS} has precedence.
  298 	@item{@var{GREP_COLORS}}
  299 		The color (@arg{mt} or @arg{ms}) to use for @option{--color}; see @xref{grep,1}.
  300 	@item{@var{GTAGSBLANKENCODE}}
  301 		If this variable is set, the @option{--encode-path=" <TAB>"}
  302 		option is specified.
  303 	@item{@var{GTAGSCACHE}}
  304 		The size of the B-tree cache. The default is 50000000 (bytes).
  305 	@item{@var{GTAGSCONF}}
  306 		Configuration file.
  307 	@item{@var{GTAGSDBPATH}}
  308 		The directory in which the tag files exist.
  309 		This value is ignored when @var{GTAGSROOT} is not defined.
  310 		Use of this variable is not recommended.
  311 	@item{@var{GTAGSFORCECPP}}
  312 		If this variable is set, each file whose suffix is @file{.h} is treated
  313 		as a C++ source file.
  314 	@item{@var{GTAGSLABEL}}
  315 		Configuration label. The default is @arg{default}.
  316 	@item{@var{GTAGSLIBPATH}}
  317 		If this variable is set, it is used as the path to search
  318 		for library functions. If the given symbol is not
  319 		found in the current project, @name{global} also searches in these paths.
  320 		Since only @file{GTAGS} is targeted in the retrieval, this variable is
  321 		ignored when @option{-r} or @option{-s} is specified.
  322 	@item{@var{GTAGSLOGGING}}
  323 		If this variable is set, @file{$GTAGSLOGGING} is used as the path name
  324 		of a log file. There is no default value.
  325 	@item{@var{GTAGSROOT}}
  326 		The root directory of the project.
  327 		Usually, it is recognized by existence of @file{GTAGS}.
  328 		Use of this variable is not recommended.
  329 	@item{@var{GTAGSTHROUGH}}
  330 		If this variable is set, the @option{-T} option is specified.
  331 	@item{@var{GTAGSOBJDIR}, @var{MAKEOBJDIR}}
  332 		If eigher of the two variable is set, it is used as the name of BSD-style objdir.
  333 		The former is given priority. The default is @file{obj}.
  334 	@item{@var{GTAGSOBJDIRPREFIX}, @var{MAKEOBJDIRPREFIX}}
  335 		If eigher of the two variable is set, it is used as the prefix of BSD-style objdir.
  336 		The former is given priority. The default is @file{/usr/obj}.
  337 	@end_itemize
  338 @CONFIGURATION
  339 	The following configuration variables affect the execution of @name{global}:
  340 
  341 	@begin_itemize
  342 	@item{@code{icase_path} (boolean)}
  343 		Ignore case distinctions in @arg{pattern}.
  344 	@end_itemize
  345 
  346 @DIAGNOSTICS
  347 	@name{Global} exits with a non-0 value if an error occurred, 0 otherwise.
  348 @SEE ALSO
  349 	@xref{gtags,1},
  350 	@xref{htags,1},
  351 	@xref{less,1},
  352 	@xref{gtags.conf,5}.
  353 
  354         GNU GLOBAL source code tag system@br
  355         (http://www.gnu.org/software/global/).
  356 @AUTHOR
  357 	Shigio YAMAGUCHI, Hideki IWAMOTO and others.
  358 @HISTORY
  359 	The @name{global} command appeared in FreeBSD 2.2.2.