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 .IP \fB\-b\fP
  83 Search for binaries.
  84 .IP \fB\-m\fP
  85 Search for manuals.
  86 .IP \fB\-s\fP
  87 Search for sources.
  88 .IP \fB\-u\fP
  89 Only show the command names that have unusual entries.  A command is said to be
  90 unusual if it does not have just one entry of each explicitly requested type.
  91 Thus
  92 .RB ' "whereis \-m \-u *" '
  93 asks for those files in the current directory which have no documentation file,
  94 or more than one.
  95 .IP "\fB\-B \fIlist\fP"
  96 Limit the places where
  97 .B whereis
  98 searches for binaries, by a whitespace-separated list of directories.
  99 .IP "\fB\-M \fIlist\fP"
 100 Limit the places where
 101 .B whereis
 102 searches for manuals and documentation in Info format, by a
 103 whitespace-separated list of directories.
 104 .IP "\fB\-S \fIlist\fP"
 105 Limit the places where
 106 .B whereis
 107 searches for sources, by a whitespace-separated list of directories.
 108 .IP "\fB\-f\fP"
 109 Terminates the directory list and signals the start of filenames.  It
 110 .I must
 111 be used when any of the
 112 .BR \-B ,
 113 .BR \-M ,
 114 or
 115 .B \-S
 116 options is used.
 117 .IP "\fB\-l"
 118 Output the list of effective lookup paths that
 119 .B whereis
 120 is using.  When none of
 121 .BR \-B ,
 122 .BR \-M ,
 123 or
 124 .B \-S
 125 is specified, the option will output the hard-coded paths
 126 that the command was able to find on the system.
 127 .TP
 128 \fB\-h\fR, \fB\-\-help\fR
 129 Display help text and exit.
 130 .TP
 131 \fB\-V\fR, \fB\-\-version\fR
 132 Display version information and exit.
 133 .SH FILE SEARCH PATHS
 134 By default
 135 .B whereis
 136 tries to find files from hard-coded paths, which are defined with glob
 137 patterns.  The command attempts to use the contents of
 138 .B $PATH
 139 and
 140 .B $MANPATH
 141 environment variables as default search path.  The easiest way to know
 142 what paths are in use is to add the
 143 .B \-l
 144 listing option.  Effects of the
 145 .BR \-B ,
 146 .BR \-M ,
 147 and
 148 .B \-S
 149 are displayed with
 150 .BR \-l .
 151 .SH ENVIRONMENT
 152 .IP WHEREIS_DEBUG=all
 153 enables debug output.
 154 .SH EXAMPLES
 155 To find all files in
 156 .I /usr/\:bin
 157 which are not documented
 158 in
 159 .I /usr/\:man/\:man1
 160 or have no source in
 161 .IR /usr/\:src :
 162 .IP
 163 .B cd /usr/bin
 164 .br
 165 .B whereis \-u \-ms \-M /usr/man/man1 \-S /usr/src \-f *
 166 .SH AVAILABILITY
 167 The whereis command is part of the util-linux package and is available from
 168 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 169 Linux Kernel Archive
 170 .UE .