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