.\"  $HeadURL$ $LastChangedRevision$
.\"
.TH LOC 1 "SPPSYM_RELEASE_DATE_MAN"
.ne 5
.SH NAME
loc \- locate a file quickly
.br
.ne 5
.SH SYNOPSIS
.B loc
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel
] [
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
] 
[
.B \-c
.I dir
|
.B \-\-cache\-dir=\fIdir
] 
{
.B \-g
|
.B \-\-generate
|
.I regex
} 
.br
.ne 5
.SH DESCRIPTION
This manual page documents version SPPSYM_RELEASE_ID of
.B loc\fR.
.PP
.B Loc
is a simple script to either cache a complete list of files under your
home directory, or to 
.B egrep\fR(1)
through that list for 
.I regex\fR. 
The cached file list is compressed with 
.B gzip\fR(1).
.ne 5
.SH CONFIGURATION
Ideally, you should call
.B loc
with the 
.B \-g
option from a daily crontab entry.
.br
.ne 5
.SH OPTIONS
.TP 25
.B \-c \fIdir\fR, \fB\-\-cache\-dir=\fIdir\fR
The directory where the cache file is may be specified with this option.
However, it is much more convenient to use the 
.B LOC_CACHE_DIR
environment variable.
.TP
.B \-d \fIlevel\fR, \fB\-\-debug=\fIlevel\fR
Determines how verbose
.B loc
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP 25
.B \-g\fR, \fB\-\-generate
Generate the cache file.
.TP
.B \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled-in paths of various files and directories that
.B loc
uses.
.TP 
.B \-v\fR, \fB\-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-V\fR, \fB\-\-version
Print the program's version number and exit.
.br
.ne 5
.SH EXIT STATUS
On success
.B loc
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.TP 25
.B $LOC_CACHE_DIR/\fIhost\fB-\fIusername
The file list cache.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.TP 25
.B LOC_CACHE_DIR
This variable specifies the location of the cache file.
.br
.ne 5
.SH EXAMPLES
The following commands generate the cache, and then search it for
\(oqfoo':
.IP
.nf
.fam C
.B LOC_CACHE_DIR=$HOME/var/loc
.B export LOC_CACHE_DIR
.B mkdir $LOC_CACHE_DIR
.B loc -g
.B loc foo
.fam T
.fi
.br
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH SEE ALSO
egrep(1), gzip(1), regexp(7)
.br
.ne 5
.SH AUTHOR
SPPSYM_AUTHOR_NAME <SPPSYM_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1999-SPPSYM_RELEASE_YEAR SPPSYM_AUTHOR_NAME
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.