"Fossies" - the Fresh Open Source Software Archive

Member "global-6.6.5/doc/global.ref" (3 Sep 2020, 14035 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 "global.ref": 6.6.4_vs_6.6.5.

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