/usr.bin/whereis/whereis.1

  1.\" Copyright (c) 1993
  2.\"	The Regents of the University of California.  All rights reserved.
  3.\"
  4.\" Copyright 2002	Joerg Wunsch
  5.\"
  6.\" Redistribution and use in source and binary forms, with or without
  7.\" modification, are permitted provided that the following conditions
  8.\" are met:
  9.\" 1. Redistributions of source code must retain the above copyright
 10.\"    notice, this list of conditions and the following disclaimer.
 11.\" 2. Redistributions in binary form must reproduce the above copyright
 12.\"    notice, this list of conditions and the following disclaimer in the
 13.\"    documentation and/or other materials provided with the distribution.
 14.\" 3. All advertising materials mentioning features or use of this software
 15.\"    must display the following acknowledgement:
 16.\"	This product includes software developed by the University of
 17.\"	California, Berkeley and its contributors.
 18.\" 4. Neither the name of the University nor the names of its contributors
 19.\"    may be used to endorse or promote products derived from this software
 20.\"    without specific prior written permission.
 21.\"
 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 25.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 32.\" SUCH DAMAGE.
 33.\"
 34.\"	@(#)whereis.1	8.2 (Berkeley) 12/30/93
 35.\"
 36.\" $FreeBSD$
 37.\"
 38.Dd August 22, 2002
 39.Dt WHEREIS 1
 40.Os
 41.Sh NAME
 42.Nm whereis
 43.Nd locate programs
 44.Sh SYNOPSIS
 45.Nm
 46.Op Fl abmqsux
 47.Op Fl BMS Ar dir ... Fl f
 48.Ar program ...
 49.Sh DESCRIPTION
 50The
 51.Nm
 52utility checks the standard binary, manual page, and source
 53directories for the specified programs, printing out the paths of any
 54it finds.
 55The supplied program names are first stripped of leading
 56path name components, any single trailing extension added by
 57.Xr gzip 1 ,
 58.Xr compress 1 ,
 59or
 60.Xr bzip2 1 ,
 61and the leading
 62.Ql s.\&
 63or trailing
 64.Ql ,v
 65from a source code control system.
 66.Pp
 67The default path searched is the string returned by the
 68.Xr sysctl 8
 69utility for the
 70.Dq user.cs_path
 71string, with
 72.Pa /usr/libexec ,
 73.Pa /usr/games
 74and the current user's
 75.Ev $PATH
 76appended.
 77Manual pages are searched by default along the
 78.Ev $MANPATH .
 79Program sources are located in a list of known standard places,
 80including all the subdirectories of
 81.Pa /usr/src
 82and
 83.Pa /usr/ports .
 84.Pp
 85The following options are available:
 86.Bl -tag -width indent
 87.It Fl B
 88Specify directories to search for binaries.
 89Requires the
 90.Fl f
 91option.
 92.It Fl M
 93Specify directories to search for manual pages.
 94Requires the
 95.Fl f
 96option.
 97.It Fl S
 98Specify directories to search for program sources.
 99Requires the
100.Fl f
101option.
102.It Fl a
103Report all matches instead of only the first of each requested type.
104.It Fl b
105Search for binaries.
106.It Fl f
107Delimits the list of directories after the
108.Fl B ,
109.Fl M ,
110or
111.Fl S
112options, and indicates the beginning of the
113.Ar program
114list.
115.It Fl m
116Search for manual pages.
117.It Fl q
118.Pq Dq quiet .
119Suppress the output of the utility name in front of the normal
120output line.
121This can become handy for use in a backquote substitution of a
122shell command line, see
123.Sx EXAMPLES .
124.It Fl s
125Search for source directories.
126.It Fl u
127Search for
128.Dq unusual
129entries.
130A file is said to be unusual if it does not have at least
131one entry of each requested type.
132Only the name of the unusual entry is printed.
133.It Fl x
134Do not use
135.Dq expensive
136tools when searching for source directories.
137Normally, after unsuccessfully searching all the first-level
138subdirectories of the source directory list,
139.Nm
140will ask
141.Xr locate 1
142to find the entry on its behalf.
143Since this can take much longer, it can be turned off with
144.Fl x .
145.El
146.Sh EXAMPLES
147The following finds all utilities under
148.Pa /usr/bin
149that do not have documentation:
150.Pp
151.Dl whereis -m -u /usr/bin/*
152.Pp
153Change to the source code directory of
154.Xr ls 1 :
155.Pp
156.Dl cd `whereis -sq ls`
157.Sh SEE ALSO
158.Xr find 1 ,
159.Xr locate 1 ,
160.Xr man 1 ,
161.Xr which 1 ,
162.Xr sysctl 8
163.Sh HISTORY
164The
165.Nm
166utility appeared in
167.Bx 3.0 .
168This version re-implements the historical
169functionality that was lost in
170.Bx 4.4 .
171.Sh AUTHORS
172This implementation of the
173.Nm
174command was written by
175.An J\(:org Wunsch .
176.Sh BUGS
177This re-implementation of the
178.Nm
179utility is not bug-for-bug compatible with historical versions.
180It is believed to be compatible with the version that was shipping with
181.Fx 2.2
182through
183.Fx 4.5
184though.
185.Pp
186The
187.Nm
188utility can report some unrelated source entries when the
189.Fl a
190option is specified.