.\" SUCH DAMAGE.
.\"
.\" @(#)whereis.1 from UCB 4.2
-.TH WHEREIS 1 "July 2009" "util-linux" "User Commands"
+.TH WHEREIS 1 "October 2014" "util-linux" "User Commands"
.SH NAME
whereis \- locate the binary, source, and manual page files for a command
.SH SYNOPSIS
.B whereis
-.RB [ \-bmsu ]
+[options]
.RB [ \-BMS
-.IR directory ...
-.BR \-f ]
-.IR filename ...
-.IX "whereis command" "" "\fLwhereis\fP \(em find program"
-.IX find "program \(em \fLwhereis\fP"
-.IX "locate program" "" "locate program \(em \fLwhereis\fP"
-.IX command locate "" "locate \(em \fLwhereis\fP"
+.IR directory "... " \fB\-f\fR ]
+.IR name ...
.SH DESCRIPTION
.B whereis
-locates source/binary and manuals sections for specified
-files.
-The supplied names are first stripped of leading pathname components
-and any (single) trailing extension of the form
-.BI . ext\fR,\fP
-for example,
-.BR .c .
+locates the binary, source and manual files for the specified command names.
+The supplied names are first stripped of leading pathname components and any
+(single) trailing extension of the form
+.BI . ext
+(for example:
+.BR .c )
Prefixes of
.B s.
resulting from use of source code control are also dealt with.
.B whereis
-then attempts to locate the desired program in
-a list of standard Linux places.
+then attempts to locate the desired program in the standard Linux places, and
+in the places specified by
+.B $PATH
+and
+.BR $MANPATH .
+.sp
+The search restrictions (options \fB\-b\fP, \fB\-m\fP and \fB\-s\fP)
+are cumulative and apply to the subsequent \fIname\fP patterns on
+the command line. Any new search restriction resets the search mask.
+For example,
+.RS
+.sp
+.B "whereis -bm ls tr -m gcc"
+.sp
+.RE
+searches for "ls" and "tr" binaries and man pages, and for "gcc" man pages only.
+.sp
+The options \fB\-B\fP, \fB\-M\fP and \fB\-S\fP reset search paths for the
+subsequent \fIname\fP patterns. For example,
+.RS
+.sp
+.B "whereis -m ls -M /usr/share/man/man1 -f cal"
+.sp
+.RE
+searches for "ls" man pages in all default paths, but for "cal" in
+the /usr/share/man/man1 directory only.
+
.SH OPTIONS
.TP
-.B \-b
-Search only for binaries.
-.TP
-.B \-m
-Search only for manual sections.
-.TP
-.B \-s
-Search only for sources.
-.TP
-.B \-u
-Search for unusual entries. A file is said to be unusual if it does
-not have one entry of each requested type.
+.IP \fB\-b\fP
+Search for binaries.
+.IP \fB\-m\fP
+Search for manuals.
+.IP \fB\-s\fP
+Search for sources.
+.IP \fB\-u\fP
+Only show the command names that have unusual entries. A command is said to be
+unusual if it does not have just one entry of each explicitly requested type.
Thus
-.RB ` "whereis\ \ \-m\ \ \-u\ \ *" '
-asks for those files in the current
-directory which have no documentation.
-.TP
-.B \-B
-Change or otherwise limit the places where
+.RB ' "whereis \-m \-u *" '
+asks for those files in the current directory which have no documentation file,
+or more than one.
+.IP "\fB\-B \fIlist\fP"
+Limit the places where
.B whereis
-searches for binaries.
-.TP
-.B \-M
-Change or otherwise limit the places where
+searches for binaries, by a whitespace-separated list of directories.
+.IP "\fB\-M \fIlist\fP"
+Limit the places where
.B whereis
-searches for
-manual sections.
-.TP
-.B \-S
-Change or otherwise limit the places where
+searches for manuals and documentation in Info format, by a
+whitespace-separated list of directories.
+.IP "\fB\-S \fIlist\fP"
+Limit the places where
.B whereis
-searches for sources.
-.TP
-.B \-f
-Terminate the last directory list and signals the start of file names,
-and
+searches for sources, by a whitespace-separated list of directories.
+.IP "\fB\-f\fP"
+Terminates the directory list and signals the start of filenames. It
.I must
be used when any of the
.BR \-B ,
.BR \-M ,
or
.B \-S
-options are used.
+options is used.
+.IP "\fB\-l"
+Output the list of effective lookup paths that
+.B whereis
+is using. When none of
+.BR \-B ,
+.BR \-M ,
+or
+.B \-S
+is specified, the option will output the hard-coded paths
+that the command was able to find on the system.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display help text and exit.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Display version information and exit.
.SH EXAMPLE
-Find all files in
-.B /usr/bin
+To find all files in
+.I /usr/\:bin
which are not documented
in
-.B /usr/man/man1
-with source in
-.BR /usr/src :
+.I /usr/\:man/\:man1
+or have no source in
+.IR /usr/\:src :
.IP
-.nf
-.ft B
-example% cd /usr/bin
-example% whereis \-u \-M /usr/man/man1 \-S /usr/src \-f *
-.fi
-.ft R
-.SH FILES
-.TP 20
-.B /{bin,sbin,etc}
-.TP
-.B /usr/{lib,bin,old,new,local,games,include,etc,src,man,sbin,
-.B X386,TeX,g++-include}
-.TP
-.B /usr/local/{X386,TeX,X11,include,lib,man,etc,bin,games,emacs}
-.SH "SEE ALSO"
-.BR chdir (2V)
-.SH BUGS
-Since
+.B cd /usr/bin
+.br
+.B whereis \-u \-ms \-M /usr/man/man1 \-S /usr/src \-f *
+.SH "FILE SEARCH PATHS"
+By default
.B whereis
-uses
-.BR chdir (2V)
-to run faster, pathnames given with the
+tries to find files from hard-coded paths, which are defined with glob
+patterns. The command attempts to use the contents of
+.B $PATH
+and
+.B $MANPATH
+environment variables as default search path. The easiest way to know
+what paths are in use is to add the
+.B \-l
+listing option. Effects of the
+.BR \-B ,
.BR \-M ,
-.BR \-S ,
-or
-.B \-B
-must be full; that is, they must begin with a
-.RB ` / '.
+and
+.B \-S
+are displayed with
+.BR \-l .
.PP
-.B whereis
-has a hard-coded path, so may not always find what
-you're looking for.
+.SH ENVIRONMENT
+.IP WHEREIS_DEBUG=all
+enables debug output.
.SH AVAILABILITY
The whereis command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .
projects / thirdparty / util-linux.git / blobdiff