Complete rewrite, once again.

This is basically a ``C compilation'' of the former whereis.pl file,
employing the same algorithms, and aiming at being mostly
UI-compatible to the old (legally tainted) 4.3BSD whereis(1).  In
comparision, the 4.4BSD-Lite version is just another variant of
which(1) only, where in particular the option to search for source
directories is sorely missing.

While i was at it, i added two more options which i contemplated doing
long since.  -x will suppress the run of locate(1) to find sources
that could not be found otherwise, potentially saving a lot of time
(but obviously, risking to not find some sources that are well hidden
in the tree).  -q will omit the leading name of the query, so in
particular, you can now do something like:

	cd `whereis -qs ls`

I'd explicitly like to thank johan for his review which was quite a
bit more than an average review, including sending me a lot of diffs.

Reviewed by:	johan

1 files changed, 119 insertions, 12 deletions

diff --git a/usr.bin/whereis/whereis.1 b/usr.bin/whereis/whereis.1
index c9cb55a..c286edb 100644
--- a/usr.bin/whereis/whereis.1
+++ b/usr.bin/whereis/whereis.1
@@ -1,9 +1,8 @@
-.\"	$NetBSD: whereis.1,v 1.12 2001/12/01 16:43:27 wiz Exp $
-.\"	$FreeBSD$
-.\"
 .\" Copyright (c) 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
+.\" Copyright 2002	Joerg Wunsch
+.\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
@@ -32,9 +31,11 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"	@(#)whereis.1	8.3 (Berkeley) 4/27/95
+.\"	@(#)whereis.1	8.2 (Berkeley) 12/30/93
+.\"
+.\" $FreeBSD$
 .\"
-.Dd April 27, 1995
+.Dd July 11, 2002
 .Dt WHEREIS 1
 .Os
 .Sh NAME
@@ -42,27 +43,133 @@
 .Nd locate programs
 .Sh SYNOPSIS
 .Nm
+.Op Fl bmqsux
+.Op Fl BMS Ar dir Ar ... Fl f
 .Ar program ...
 .Sh DESCRIPTION
 The
 .Nm
-utility checks the standard binary directories for the specified programs,
-printing out the paths of any it finds.
+utility checks the standard binary, manual page, and source
+directories for the specified programs, printing out the paths of any
+it finds.  The supplied program names are first stripped of leading 
+path name components, any single trailing extension added by
+.Xr gzip 1 ,
+.Xr compress 1 ,
+or
+.Xr bzip2 1 ,
+and the leading
+.Ql s.\&
+or trailing
+.Ql ,v
+from a source code control system.
 .Pp
 The default path searched is the string returned by the
 .Xr sysctl 8
 utility for the
 .Dq user.cs_path
-string.
+string, with
+.Pa /usr/libexec
+and the current user's
+.Ev $PATH
+appended.  Manual pages are searched by default along the
+.Ev $MANPATH .
+Program sources are located in a list of known standard places,
+including all the subdirectories of
+.Pa /usr/src
+and
+.Pa /usr/ports .
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl B
+Specify directories to search for binaries.  Requires the
+.Fl f
+option.
+.It Fl M
+Specify directories to search for manual pages.  Requires the
+.Fl f
+option.
+.It Fl S
+Specify directories to search for program sources.  Requires the
+.Fl f
+option.
+.It Fl b
+Search for binaries.
+.It Fl f
+Delimits the list of directories after the
+.Fl B ,
+.Fl M ,
+or
+.Fl S
+options, and indicates the beginning of the
+.Ar program
+list.
+.It Fl m
+Search for manual pages.
+.It Fl q
+.Pq Dq quiet .
+Suppress the output of the utility name in front of the normal
+output line.
+This can become handy for use in a backquote substitution of a
+shell command line, see
+.Sx EXAMPLES .
+.It Fl s
+Search for source directories.
+.It Fl u
+Search for
+.Dq unusual
+entries.  A file is said to be unusual if it does not have one entry
+of each requested type.
+Only the name of the unusual entry is printed.
+.It Fl x
+Do not use
+.Dq expensive
+tools when searching for source directories.
+Normally, after unsuccessfully searching all the first-level
+subdirectories of the source directory list,
+.Nm
+will ask
+.Xr locate 1
+to find the entry on its behalf.
+Since this can take much longer, it can be turned off with
+.Fl x .
+.El
+.Sh EXAMPLES
+The following finds all utilities under
+.Pa /usr/bin
+that do not have documentation:
+.Pp
+.Dl whereis -m -u /usr/bin/*
+.Pp
+Change to the source code directory of
+.Xr ls 1 :
+.Pp
+.Dl cd `whereis -sq ls`
 .Sh SEE ALSO
+.Xr find 1 ,
+.Xr locate 1 ,
+.Xr man 1 ,
 .Xr which 1 ,
 .Xr sysctl 8
-.Sh COMPATIBILITY
-The historic flags and arguments for the
-.Nm
-utility are no longer available in this version.
 .Sh HISTORY
 The
 .Nm
 command appeared in
 .Bx 3.0 .
+This version re-implements the historical
+functionality that was lost in
+.Bx 4.4 .
+.Sh AUTHORS
+This implementation of the
+.Nm
+command was written by
+.An J\(:org Wunsch .
+.Sh BUGS
+This re-implementation of the
+.Nm
+utility is not bug-for-bug compatible with historical versions.
+It is believed to be compatible with the version that was shipping with
+.Fx 2.2
+through
+.Fx 4.5
+though.