.TH g.findfile
.SH NAME
\fIg.findfile\fR  \- Searches for GRASS data base files and sets variables
for the shell.
.br
.I "(GRASS File Management Program)"
.SH SYNOPSIS
.B g.findfile
.br
\fBg.findfile help\fR
.br
\fBg.findfile element\*=\fIname\fR [\fBmapset\*=\fIname\fR] \fBfile\*=\fIname\fR
.SH DESCRIPTION
.I g.findfile
is designed for Bourne shell scripts that need to search for raster map
layer files, vector files, site list files,
geographic region definition (windows) files, and imagery group files
in the GRASS data base.
If the user runs \fIg.findfile\fR without command line arguments,
he will be prompted for the names of a GRASS element, file, and mapset,
through the standard parser interface (see manual entry for \fIparser\fR).
.LP
\fBParameters:\fR
.IP \fBelement\*=\fIname\fR 18
The data base element (i.e., directory within a GRASS mapset) to be searched.
.IP \fBmapset\*=\fIname\fR 18
The mapset in which to search for the specified file \fIname\fR.
If not specified, all mapsets in the user's GRASS search path
are searched.  Otherwise, the specified mapset is searched.  As a convenience,
if specified as a single dot (.) only the current mapset is searched.
.IP \fBfile\*=\fIname\fR 18
The name of a GRASS data file (of the stated \fIelement\fR type) for which to search.
.SH OUTPUT
.I g.findfile
writes four lines to standard output:

.nf
.RS
name\*='\fIfile_name\fR'
mapset\*='\fImapset_name\fR'
file\*='\fIunix_filename\fR'
fullname\*='\fIgrass_fullname\fR'
.RE
.fi

The output is /bin/sh commands to set the variable
.I name
to the GRASS data base file name, 
.I mapset
to the mapset in which the file resides, and 
.I file
to the full UNIX path name for the named file.
These variables may be set in the /bin/sh as follows:

.RS
\fBeval \(gag.findfile element\*=\fIname \fBmapset\*=\fIname \fBname\*=\fIname\fR\(ga
.RE
.SH NOTES
If the specified file does not exist, the variables will be set as follows:
.nf
.RS
name\*=
mapset\*=
fullname\*=
file\*=
.RE
.fi

The following is a way to test for this case:

.nf
.RS
if [ ! \*(lq$file\*(rq ]
then
.RS
exit
.RE
fi
.RE
.SH "SEE ALSO"
.I g.ask,
.I g.filename,
.I g.gisenv,
.I g.mapsets,
and
.I parser
.SH AUTHOR
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory