Provided by: global_6.6.13-1_amd64 bug

NAME

       global - print locations of given symbols

SYNOPSIS

       global [-adEFGilMnNqrstTvx][-S dir][-e] pattern
       global -c[dFiIMoOPqrsTv] prefix
       global -f[adlnqrstvx][-L file-list][-S dir] files
       global -g[aEGilMnoOqtvVx][-L file-list][-S dir][-e] pattern [files]
       global -I[ailMnqtvx][-S dir][-e] pattern
       global -P[aEGilMnoOqtvVx][-S dir][-e] pattern
       global -p[qrv]
       global -u[qv]

DESCRIPTION

       Global  finds  locations of given symbols in C, Yacc, Java, PHP and assembly source files,
       and prints the path name, line number and line image of the locations.  Global can  locate
       not only definitions but also references and other symbols.

       Global  can  treat a source tree, that is, a directory that has sub-directories and source
       files, as a project.  In advance of using this command, you must execute gtags(1)  at  the
       root  directory  of the project which you want to investigate to make tag files.  Then you
       can use global command anywhere in the project.  You need not specify where the  tag  file
       is.  Instead, global locates it by itself.

       You  can  specify  a  regular  expression  for  pattern.  Global understands two different
       versions of regular expression syntax: basic and extended (default).

COMMANDS

       The following commands are available:

       <no command> pattern
              No command means tag search command.   Print  tags  which  match  to  pattern.   By
              default, print definition tags.

       -c, --completion[=limit] [prefix]
              Print  symbols which start with prefix.  If prefix is not given, print all symbols.
              If limit is given, print up to limit lines.

       -f, --file files
              Print all tags in the files.  This command implies the -x option.

       -g, --grep pattern [files]
              Print all lines which match to the pattern.   If  files  are  given,  this  command
              searches in those files.

       --help Print a usage message.

       -I, --idutils pattern
              Print  all lines which match to pattern.  This function uses idutils(1) as a search
              engine.  To use this command, you need to install idutils(1)  in  your  system  and
              execute gtags(1) with the -I option.

       -P, --path [pattern]
              Print  path  names which match to pattern.  If no pattern is given, print all paths
              in the project.

       -p, --print-dbpath
              Print location of ´GTAGS´.

       --print name
              Print location of name, which may be one of: ´root´, ´dbpath´  or  ´conf´.   ´root´
              means  project's  root  directory.  ´dbpath´  means a directory where tag databases
              exist. ´conf´ means configuration file.

       -u, --update
              Update tag files incrementally.  This command internally invokes gtags(1).  You can
              execute this command anywhere in the project, differing from gtags(1).

       --version
              Show version number.

OPTIONS

       The following options are available:

       -a, --absolute
              Print absolute path names. By default, print relative path names.

       --color when
              Use  color  to  highlight  the  pattern within the line; when may be one of: never,
              always or  auto  (default).   The  default  color  is  bold  red  text  on  current
              background;  the  environment variable GREP_COLORS (only mt and ms are effective at
              present) or GREP_COLOR defines it.  This  option  is  effective  to  the  following
              commands: <no command>, -f, -g, -I, -P.

       -C, --directory dir
              Change the directory before doing all the work including parameter analysis.

       -d, --definition
              Print locations of definitions.

       -e, --regexp pattern
              Use pattern as the pattern; useful to protect patterns starting with ´-´.

       -E, --extended-regexp
              Interpret pattern as a extended regular expression.  This is the default.

       --encode-path chars
              Convert  path  characters  in  chars  into  a ´%´ symbol, followed by the two-digit
              hexadecimal representation of the character.  A blank will be converted to ´%20´.

       -F, --first-match
              End the search without going through all the tag files listed in GTAGSLIBPATH  when
              tags are found in a tag file. This is the default.

       --from-here context
              Decide  tag type by context. Its syntax should be ´lineno:path´.  If the context is
              a definition of the pattern then use -r, else if there is at least  one  definition
              of  the  pattern then use -d, else use -s.  If this option is specified then -d, -r
              and -s on the command line are ignored.  Regular  expression  is  not  allowed  for
              pattern.   This  option  assumes use in conversational environments such as editors
              and IDEs.

       -G, --basic-regexp
              Interpret pattern as a basic  regular  expression.   The  default  is  an  extended
              regular expression.

       --gtagsconf file
              Set environment variable GTAGSCONF to file.

       --gtagslabel label
              Set environment variable GTAGSLABEL to label.

       -i, --ignore-case
              Ignore case distinctions in the pattern.

       -L, --file-list file
              Obtain  files from file in addition to the arguments.  The argument file can be set
              to '-' to accept a list of files from  the  standard  input.  File  names  must  be
              separated by newline.

       -l, --local
              Print only tags which exist under the current directory.

       --literal
              Execute  literal  search  instead  of regular expression search.  This option works
              with the tag search command, -g command, -P command and -I command.

       -M, --match-case
              Search is case-sensitive. This is the default.

       --match-part part
              Specify how path name completion should match,  where  part  is  one  of:  ´first´,
              ´last´  or  ´all´  (default).   This  option  is  valid only with the -c command in
              conjunction with -P.

       -n, --nofilter
              Suppress sort filter and path conversion filter.

       -N, --nearness[=start]
              Use Nearness sort method (sorting by  closest  from  start)  for  the  output.   By
              default,  alphabetical  sort  method is used.  This option is effective for the tag
              search command, -P command and -g command. As an exception, -g command ignores this
              option  when files are specified by arguments.  The nearness is defined by how many
              parent directories to go up to reach the target. The result  of  nearness  sort  is
              concatenation of the following ([0]-[n]) in this order. The default of start is the
              current directory.
              [0] If the start is a file, output of local search in the file.
              [1] Output of local search in the start directory except for [0].
              [2] Output of local search in the parent directory except for [0]-[1].
              [3] Output of local search in the grandparent directory except for [0]-[2].
              ... (repeat until the project root directory)
              [n] Output of local search in the project root directory except for [0]-[n-1].
              In each directory, they are sorted by alphabetical order.

       -O, --only-other
              Treat only text files other than source code, like ´README´.  This option is  valid
              only with the -g or -P command.  This option overrides the -o option.

       -o, --other
              Treat  not  only  source  files  but  also  text files other than source code, like
              ´README´.  This option is valid only with the -g or -P command.

       --path-style format
              Print path names using  format,  which  may  be  one  of:  ´relative´,  ´absolute´,
              ´shorter´, ´abslib´ or ´through´.  ´relative´ means relative path. ´absolute´ means
              absolute path.  ´shorter´ means the shorter one  of  relative  and  absolute  path.
              ´abslib´ means absolute path for libraries (GTAGSLIBPATH) and relative path for the
              rest.  ´through´ means the relative path from the project root directory  (internal
              format  of  GPATH).   The  default is ´relative´.  The --path-style option is given
              more priority than the -a option.

       --print0
              Print each record followed by a null character instead of a newline.

       -q, --quiet
              Quiet mode.

       -r, --reference, --rootdir
              Print reference tags.   Reference  means  the  reference  to  a  symbol  which  has
              definitions.  With the -p option, print the root directory of the project.

       --result format
              Print  out using format, which may be one of: ´path´ (default), ´ctags´, ´ctags-x´,
              ´grep´ or ´cscope´.  The --result=ctags and --result=ctags-x options are equivalent
              to  the -t and -x options respectively.  The --result option is given more priority
              than the -t and -x options.

       --single-update file
              Update tag files using gtags(1) with the --single-update option.  It is  considered
              that  file  was  added,  updated or deleted, and there is no change in other files.
              This option implies the -u option.

       -s, --symbol
              Print other symbol tags.  Other symbol means the reference to a symbol which has no
              definition.

       -S, --scope dir
              Print  only  tags which exist under dir directory.  It is similar to the -l option,
              but you need not change directory.

       -T, --through
              Go through all the tag files listed in GTAGSLIBPATH.  By  default,  stop  searching
              when  tag  is  found.   This  option  is ignored when either -s, -r or -l option is
              specified.

       -t, --tags
              Use standard ctags format.

       -V, --invert-match
              Invert the sense of matching, to select non-matching lines.  This option  is  valid
              only with the -g or -P commands.

       -v, --verbose
              Verbose mode.

       -x, --cxref
              Use standard ctags cxref (with -x) format.

EXAMPLES

       $ ls -F
       Makefile      src/    lib/
       $ gtags
       $ ls G*
       GPATH   GRTAGS  GTAGS
       $ global main
       src/main.c
       $ (cd src; global main)
       main.c
       $ global -x main
       main              10 src/main.c  main (argc, argv) {
       $ global -f src/main.c
       main              10 src/main.c  main (argc, argv) {
       func1             55 src/main.c  func1() {
       func2             72 src/main.c  func2() {
       func3            120 src/main.c  func3() {
       $ global -x '^[sg]et'
       set_num           20 lib/util.c  set_num(values) {
       get_num           30 lib/util.c  get_num() {
       $ global -rx set_num
       set_num          113 src/op.c            set_num(32);
       set_num          225 src/opop.c               if (set_num(0) > 0) {
       $ global strlen
       $ (cd /usr/src/sys; gtags)
       $ export GTAGSLIBPATH=/usr/src/sys
       $ global -a strlen
       /usr/src/sys/libkern/strlen.c
       $ (cd /usr/src/lib; gtags)
       $ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
       $ global -a strlen
       /usr/src/lib/libc/string/strlen.c

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

ENVIRONMENT

       The following environment variables affect the execution of global:

       GREP_COLOR
              The color to use for --color; GREP_COLORS has precedence.

       GREP_COLORS
              The color (mt or ms) to use for --color; see grep(1).

       GTAGSBLANKENCODE
              If this variable is set, the --encode-path=" <TAB>" option is specified.

       GTAGSCACHE
              The size of the B-tree cache. The default is 50000000 (bytes).

       GTAGSCONF
              Configuration file.

       GTAGSDBPATH
              The directory in which the tag files exist.  This value is ignored  when  GTAGSROOT
              is not defined.  Use of this variable is not recommended.

       GTAGSFORCECPP
              If  this variable is set, each file whose suffix is ´.h´ is treated as a C++ source
              file.

       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 given symbol is not found in the current 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.

       GTAGSLOGGING
              If  this  variable  is set, ´$GTAGSLOGGING´ is used as the path name of a log file.
              There is no default value.

       GTAGSROOT
              The root directory of the project.  Usually,  it  is  recognized  by  existence  of
              ´GTAGS´.  Use of this variable is not recommended.

       GTAGSTHROUGH
              If this variable is set, the -T option is specified.

       GTAGSOBJDIR, MAKEOBJDIR
              If  eigher  of the two variable is set, it is used as the name of BSD-style objdir.
              The former is given priority. The default is ´obj´.

       GTAGSOBJDIRPREFIX, MAKEOBJDIRPREFIX
              If eigher of the two variable is set, it is used as the prefix of BSD-style objdir.
              The former is given priority. The default is ´/usr/obj´.

CONFIGURATION

       The following configuration variables affect the execution of global:

       icase_path (boolean)
              Ignore case distinctions in pattern.

DIAGNOSTICS

       Global exits with a non-0 value if an error occurred, 0 otherwise.

SEE ALSO

       gtags(1), htags(1), less(1), gtags.conf(5).

       GNU Global source code tag system
       (http://www.gnu.org/software/global/).

AUTHOR

       Shigio YAMAGUCHI, Hideki IWAMOTO and others.

HISTORY

       The global command appeared in FreeBSD 2.2.2.