misc-utils/whereis.1

   1 .\" Copyright (c) 1980, 1990 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" @(#)whereis.1 from UCB 4.2
  33 .TH WHEREIS 1 "October 2014" "util-linux" "User Commands"
  34 .SH NAME
  35 whereis \- locate the binary, source, and manual page files for a command
  36 .SH SYNOPSIS
  37 .B whereis
  38 [options]
  39 .RB [ \-BMS
  40 .IR directory "... " \fB\-f\fR ]
  41 .IR name ...
  42 .SH DESCRIPTION
  43 .B whereis
  44 locates the binary, source and manual files for the specified command names.
  45 The supplied names are first stripped of leading pathname components and any
  46 (single) trailing extension of the form
  47 .BI . ext
  48 (for example:
  49 .BR .c )
  50 Prefixes of
  51 .B s.
  52 resulting from use of source code control are also dealt with.
  53 .B whereis
  54 then attempts to locate the desired program in the standard Linux places, and
  55 in the places specified by
  56 .B $PATH
  57 and
  58 .BR $MANPATH .
  59 .sp
  60 The search restrictions (options \fB\-b\fP, \fB\-m\fP and \fB\-s\fP)
  61 are cumulative and apply to the subsequent \fIname\fP patterns on
  62 the command line.  Any new search restriction resets the search mask.
  63 For example,
  64 .RS
  65 .sp
  66 .B "whereis \-bm ls tr \-m gcc"
  67 .sp
  68 .RE
  69 searches for "ls" and "tr" binaries and man pages, and for "gcc" man pages only.
  70 .sp
  71 The options \fB\-B\fP, \fB\-M\fP and \fB\-S\fP reset search paths for the
  72 subsequent \fIname\fP patterns.  For example,
  73 .RS
  74 .sp
  75 .B "whereis \-m ls \-M /usr/share/man/man1 \-f cal"
  76 .sp
  77 .RE
  78 searches for "ls" man pages in all default paths, but for "cal" in
  79 the /usr/share/man/man1 directory only.
  80
  81 .SH OPTIONS
  82 .TP
  83 .IP \fB\-b\fP
  84 Search for binaries.
  85 .IP \fB\-m\fP
  86 Search for manuals.
  87 .IP \fB\-s\fP
  88 Search for sources.
  89 .IP \fB\-u\fP
  90 Only show the command names that have unusual entries.  A command is said to be
  91 unusual if it does not have just one entry of each explicitly requested type.
  92 Thus
  93 .RB ' "whereis \-m \-u *" '
  94 asks for those files in the current directory which have no documentation file,
  95 or more than one.
  96 .IP "\fB\-B \fIlist\fP"
  97 Limit the places where
  98 .B whereis
  99 searches for binaries, by a whitespace-separated list of directories.
 100 .IP "\fB\-M \fIlist\fP"
 101 Limit the places where
 102 .B whereis
 103 searches for manuals and documentation in Info format, by a
 104 whitespace-separated list of directories.
 105 .IP "\fB\-S \fIlist\fP"
 106 Limit the places where
 107 .B whereis
 108 searches for sources, by a whitespace-separated list of directories.
 109 .IP "\fB\-f\fP"
 110 Terminates the directory list and signals the start of filenames.  It
 111 .I must
 112 be used when any of the
 113 .BR \-B ,
 114 .BR \-M ,
 115 or
 116 .B \-S
 117 options is used.
 118 .IP "\fB\-l"
 119 Output the list of effective lookup paths that
 120 .B whereis
 121 is using.  When none of
 122 .BR \-B ,
 123 .BR \-M ,
 124 or
 125 .B \-S
 126 is specified, the option will output the hard-coded paths
 127 that the command was able to find on the system.
 128 .TP
 129 \fB\-h\fR, \fB\-\-help\fR
 130 Display help text and exit.
 131 .TP
 132 \fB\-V\fR, \fB\-\-version\fR
 133 Display version information and exit.
 134 .SH FILE SEARCH PATHS
 135 By default
 136 .B whereis
 137 tries to find files from hard-coded paths, which are defined with glob
 138 patterns.  The command attempts to use the contents of
 139 .B $PATH
 140 and
 141 .B $MANPATH
 142 environment variables as default search path.  The easiest way to know
 143 what paths are in use is to add the
 144 .B \-l
 145 listing option.  Effects of the
 146 .BR \-B ,
 147 .BR \-M ,
 148 and
 149 .B \-S
 150 are displayed with
 151 .BR \-l .
 152 .PP
 153 .SH ENVIRONMENT
 154 .IP WHEREIS_DEBUG=all
 155 enables debug output.
 156 .SH EXAMPLE
 157 To find all files in
 158 .I /usr/\:bin
 159 which are not documented
 160 in
 161 .I /usr/\:man/\:man1
 162 or have no source in
 163 .IR /usr/\:src :
 164 .IP
 165 .B cd /usr/bin
 166 .br
 167 .B whereis \-u \-ms \-M /usr/man/man1 \-S /usr/src \-f *
 168 .SH AVAILABILITY
 169 The whereis command is part of the util-linux package and is available from
 170 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 171 Linux Kernel Archive
 172 .UE .