.\" This file is generated automatically by convert.pl from global/manual.in.
.TH GLOBAL 1 "March 2008" "GNU Project"
.SH NAME
global \- print the locations of specified object.
.SH SYNOPSIS
\fBglobal\fP [-aGilnqrstTvx][-e] \fIpattern\fP
.br
\fBglobal\fP -c[qrsv] \fIprefix\fP
.br
\fBglobal\fP -f[anqrstvx] \fIfiles\fP
.br
\fBglobal\fP -g[aGilnoOqtvx][-e] \fIpattern\fP
.br
\fBglobal\fP -I[ailnqtvx][-e] \fIpattern\fP
.br
\fBglobal\fP -P[aGilnoOqtvx][-e] \fIpattern\fP
.br
\fBglobal\fP -p[qrv]
.br
\fBglobal\fP -u[qv]
.br
.SH DESCRIPTION
\fBGlobal\fP find the locations of specified object
in C, C++, Yacc, Java, PHP and Assembly source files.
\fBGlobal\fP can treat a source tree, that is, a directory that
has sub-directories and source files as a project.
You can get the relative path of objects from anywhere within the project.
\fBGlobal\fP can locate not only object definitions but also object
references and other symbols.
.PP
In advance of using this command, you must execute \fBgtags\fP(1)
at the root directory of the project to make tag files.
Then you can execute this command at anywhere in the project.
.SH COMMANDS
The following commands are available:
.TP
<no command> \fIpattern\fP
Print object which match to the \fIpattern\fP.
Extended regular expressions which are the same as those
accepted by \fBegrep\fP(1) are available.
.TP
\fB-c\fP, \fB--completion\fP [\fIprefix\fP]
Print the candidates of object names which start with the specified
\fIprefix\fP. \fIPrefix\fP is not specified,
print all object names.
.TP
\fB-f\fP, \fB--file\fP \fIfiles\fP
Print all tags in the \fIfiles\fP.
This option implies the -x option.
.TP
\fB-g\fP, \fB--grep\fP \fIpattern\fP
Print all lines which match to the \fIpattern\fP.
.TP
\fB--help\fP
Show help.
.TP
\fB-I\fP, \fB--idutils\fP \fIpattern\fP
Print all lines which match to the \fIpattern\fP.
This function use \fBidutils\fP(1) as a search engine.
To use this command, you need to install \fBidutils\fP(1)
in your system and you must execute \fBgtags\fP(1)
with the \fB-I\fP option.
.TP
\fB-P\fP, \fB--path\fP [\fIpattern\fP]
Print the paths which match to the \fIpattern\fP.
If no pattern specified, print all paths in the project.
.TP
\fB-p\fP, \fB--print-dbpath\fP
Print the location of \'GTAGS\'.
.TP
\fB-u\fP, \fB--update\fP
Locate tag files and update them incrementally.
.TP
\fB--version\fP
Show version number.
.SH OPTIONS
The following options are available:
.TP
\fB-a\fP, \fB--absolute\fP
Print absolute path name. By default, print relative path name.
.TP
\fB--from-here\fP \fIcontext\fP
Decide tag type by the context. The \fIcontext\fP must be 'lineno:path'.
If this option is specified then the \fB-s\fP and \fB-r\fP
are ignored.
Regular expression is not allowed in the \fIpattern\fP.
This option is assumes use in conversational environments such as
editors and IDEs.
.TP
\fB-e\fP, \fB--regexp\fP \fIpattern\fP
Use \fIpattern\fP as the pattern; useful to protect  patterns
beginning with \'-\'.
.TP
\fB-G\fP, \fB--basic-regexp\fP
Interpret \fIpattern\fP as a  basic regular expression.
The default is extended regular expression.
.TP
\fB-i\fP, \fB--ignore-case\fP
ignore case distinctions in pattern.
.TP
\fB-l\fP, \fB--local\fP
Print just objects which exist under the current directory.
.TP
\fB-n\fP, \fB--nofilter\fP
Suppress sort filter and path conversion filter.
.TP
\fB-O\fP, \fB--only-other\fP
Search pattern only in other than source files like \'README\'.
This option is valid only with \fB-g\fP or \fB-P\fP command.
This option override the \fB-o\fP option.
.TP
\fB-o\fP, \fB--other\fP
Search pattern in not only source files but also other files
like \'README\'.
This option is valid only with \fB-g\fP or \fB-P\fP command.
.TP
\fB-q\fP, \fB--quiet\fP
Quiet mode.
.TP
\fB-r\fP, \fB--reference\fP, \fB--rootdir\fP
Print the locations of object references.
By default, print object definitions.
With the \fB-p\fP option, print the root directory of source tree.
.TP
\fB--result\fP \fIformat\fP
\fIformat\fP may be 'path', `ctags', `ctags-x', `grep' or 'cscope'.
The \fB--result=ctags\fP and \fB--result=ctags-x\fP are
equivalent to the \fB-t\fP and \fB-x\fP respectively.
The \fB--result\fP option is given to priority more than the -t and -x option.
.TP
\fB-s\fP, \fB--symbol\fP
Print the locations of specified symbol other than definitions.
.TP
\fB-T\fP, \fB--through\fP
Go through all the tag files listed in \fBGTAGSLIBPATH\fP.
By default, stop searching when tag is found.
This option is ignored when either \fB-s\fP, \fB-r\fP
or \fB-l\fP option is specified.
.TP
\fB-t\fP, \fB--tags\fP
Print with standard ctags format.
.TP
\fB-v\fP, \fB--verbose\fP
Verbose mode.
.TP
\fB-x\fP, \fB--cxref\fP
In addition to the default output, produce the line number and
the line contents.
.SH EXAMPLES
.nf
	$ 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)
	$ export GTAGSLIBPATH=/usr/src/sys
	$ global strlen
	../../../usr/src/sys/libkern/strlen.c
	$ (cd /usr/src/lib; gtags)
	$ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
	$ global strlen
	../../../usr/src/lib/libc/string/strlen.c
.fi
.SH FILES
.TP
\'GTAGS\'
Tag file for object definitions.
.TP
\'GRTAGS\'
Tag file for object references.
.TP
\'GSYMS\'
Tag file for other symbols.
.TP
\'GPATH\'
Tag file for path of source files.
.TP
\'GTAGSROOT\'
If environment variable \fBGTAGSROOT\fP is not set and \'GTAGSROOT\' exist
in the same directory with \'GTAGS\' then use the value
as \fBGTAGSROOT\fP.
.TP
\'/etc/gtags.conf\', \'$HOME/.globalrc\'
Configuration file.
.SH ENVIRONMENT
The following environment variables affect the execution of \fBglobal\fP:
.TP
\fBGTAGSROOT\fP
The directory which is the root of source code.
.TP
\fBGTAGSDBPATH\fP
The directory on which gtags database exist.
This value is ignored when \fBGTAGSROOT\fP is not defined.
.TP
\fBGTAGSLIBPATH\fP
If this variable is set, it is used as the path to search
for library functions. If the specified function is not
found in the source project, \fBglobal\fP also search in these paths.
.TP
\fBGTAGSLABEL\fP
If this variable is set, its value is used as the label
of configuration file. The default is default.
.TP
\fBMAKEOBJDIRPREFIX\fP
If this variable is set, \'$MAKEOBJDIRPREFIX<current directory>\'
is used as the candidate directory for tag files.
.SH CONFIGURATION
The following configuration variables affect the execution of \fBglobal\fP:
.TP
icase_path(boolean)
Ignore case distinctions in the \fIpattern\fP.
.SH DIAGNOSTICS
\fBGlobal\fP exits with a non 0 value if an error occurred, 0 otherwise.
.SH "SEE ALSO"
\fBgtags-parser\fP(1),
\fBgtags\fP(1),
\fBhtags\fP(1),
\fBless\fP(1).
.PP
GNU GLOBAL source code tag system
.br
(http://www.gnu.org/software/global/).
.SH AUTHOR
Tama Communications Corporation.
.SH HISTORY
The \fBglobal\fP command appeared in FreeBSD 2.2.2.