GLOBAL(29)

NAME
global - print the locations of specified object.

SYNOPSIS
global [-ailnqrstTvx] pattern
global -c[qsv] prefix
global -f[anqrstvx] files
global -g[ailnoqtvx] pattern
global -I[ailnqtvx] pattern
global -p[qrv]
global -P[ailnqtvx] pattern
global -u[qv]

DESCRIPTION
Global find the locations of specified object in C, C++, Yacc, Java and assembler source files. Global can treat a source tree, that is, a directory that has subdirectories and source files. You can get the relative path of objects from anywhere within the tree. Global can locate not only function definitions but also function references and other symbols. Duplicate entries are allowed.

In advance of using this command, you must execute gtags(1) at the root directory of the source tree to make tag files. Then you can execute at anywhere in the source tree.

COMMANDS
The following commands are available:

pattern
    Print object which match to the pattern. It can include POSIX 1003.2 regular expression.

-c, --completion [prefix]
    Print candidate function names which start with specified prefix. Prefix is not specified, print all function names.

-f, --file files
    Print all function definitions in the files. This option implies -x option.

-g, --grep pattern
    Print all lines which match to the pattern. This function use grep(1) as a search engine.

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

-p, --print-dbpath
    Print the location of 'GTAGS'.

-P, --path [pattern]
    Print the path which match to the pattern. If no pattern specified, print all.

-u, --update
    Locate tag files and update them incrementally.

--version
    Show version number.

--help
    Show help.

OPTIONS
The following options are available:

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

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

-l, --local
    Print just objects which exist under the current directory.

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

-o, --other
    Search pattern in not only source files but also other files like 'README'. This options is valid only with -g option.

-q, --quiet
    Quiet mode.

-r, --reference, --rootdir
    Print the locations of object references. By default, print object definitions. With the -p option, print the root directory of source tree.

-s, --symbol pattern
    Print the locations of specified symbol other than function names. You need 'GSYMS' tags file. See gtags(1).

-t, --tags
    Print with standard ctags format.

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

-v, --verbose
    Verbose mode.

-x, --cxref
    In addition to the default output, produce the line number and the line contents.

EXAMPLES
	% ls -F
	Makefile      src/    lib/
	% gtags
	% global main
	src/main.c
	% global -x main
	main              10 src/main.c  main (argc, argv) {
	% global -x '^[sg]et'
	set_num           20 lib/util.c  set_num(values)
	get_num           30 lib/util.c  get_num() {
	% global -rx '^[sg]et'
	set_num          113 src/op.c            set_num(32);
	set_num          225 src/opop.c               if (set_num(0) > 0) {
	get_num           90 src/op.c            while (get_num() > 0) {
	% cd lib
	% global -rx '^[sg]et'
	set_num          113 ../src/op.c            set_num(32);
	set_num          225 ../src/opop.c               if (set_num(0) > 0) {
	get_num           90 ../src/op.c            while (get_num() > 0) {
	% global strlen
	% (cd /usr/src/sys; gtags)
	% setenv GTAGSLIBPATH /usr/src/sys
	% global strlen
	../../../usr/src/sys/libkern/strlen.c
	% (cd /usr/src/lib; gtags)
	% setenv GTAGSLIBPATH /usr/src/lib:/usr/src/sys
	% global strlen
	../../../usr/src/lib/libc/string/strlen.c

FILES

'GTAGS'
    Tag file for function definitions.

'GRTAGS'
    Tag file for function references.

'GSYMS'
    Tag file for other symbols.

'GPATH'
    Tag file for path of source files.

'GTAGSROOT'
    If environment variable GTAGSROOT is not set and 'GTAGSROOT' exist in the same directory with 'GTAGS' then use the value as GTAGSROOT.

'/etc/gtags.conf', '$HOME/.globalrc'
    Configuration file.

ENVIRONMENT
The following environment variables affect the execution of global:

GTAGSROOT
    The directory which is the root of source tree.

GTAGSDBPATH
    The directory on which gtags database exist. This value is ignored when GTAGSROOT is not defined.

GTAGSLIBPATH
    If this variable is set, it is used as the path to search for library functions. If the specified function is not found in a source tree, global also search in these paths.

GTAGSLABEL
    If this variable is set, its value is used as the label of configuration file. The default is default.

CONFIGURATION
The following configuration variables affect the execution of global:

icase_path(boolean)
    Ignore case distinctions in the pattern.

sed_command(string)
    Use specified sed(1) command, which is used internally.

sort_command(string)
    Use specified sort(1) command, which is used internally.

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

SEE ALSO
btreeop(1), gctags(1), gtags(1), htags(1).

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

AUTHOR
Shigio Yamaguchi

HISTORY
The global command appeared in FreeBSD 2.2.2.