misc-utils/whereis.1.adoc

   1 //po4a: entry man manual
   2 ////
   3 Copyright (c) 1980, 1990 The Regents of the University of California.
   4 All rights reserved.
   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 from UCB 4.2
  35 ////
  36 = whereis(1)
  37 :doctype: manpage
  38 :man manual: User Commands
  39 :man source: util-linux {release-version}
  40 :page-layout: base
  41 :command: whereis
  42
  43 == NAME
  44
  45 whereis - locate the binary, source, and manual page files for a command
  46
  47 == SYNOPSIS
  48
  49 *whereis* [options] [*-BMS* _directory_... *-f*] _name_...
  50
  51 == DESCRIPTION
  52
  53 *whereis* locates the binary, source and manual files for the specified command names. The supplied names are *first stripped of leading pathname components*. Prefixes of *s.* resulting from use of source code control are also dealt with. *whereis* then attempts to locate the desired program in the standard Linux places, and in the places specified by *$PATH* and *$MANPATH*.
  54
  55 The search restrictions (options *-b*, *-m* and *-s*) are cumulative and apply to the subsequent _name_ patterns on the command line. Any new search restriction resets the search mask. For example,
  56
  57 ____
  58 *whereis -bm ls tr -m gcc*
  59 ____
  60
  61 searches for "ls" and "tr" binaries and man pages, and for "gcc" man pages only.
  62
  63 The options *-B*, *-M* and *-S* reset search paths for the subsequent _name_ patterns. For example,
  64
  65 ____
  66 *whereis -m ls -M /usr/share/man/man1 -f cal*
  67 ____
  68
  69 searches for "*ls*" man pages in all default paths, but for "cal" in the _/usr/share/man/man1_ directory only.
  70
  71 == OPTIONS
  72
  73 *-b*::
  74 Search for binaries.
  75
  76 *-m*::
  77 Search for manuals.
  78
  79 *-s*::
  80 Search for sources.
  81
  82 *-u*::
  83 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 '*whereis -m -u **' asks for those files in the current directory which have no documentation file, or more than one.
  84
  85 *-B* _list_::
  86 Limit the places where *whereis* searches for binaries, by a whitespace-separated list of directories.
  87
  88 *-M* _list_::
  89 Limit the places where *whereis* searches for manuals and documentation in Info format, by a whitespace-separated list of directories.
  90
  91 *-S* _list_::
  92 Limit the places where *whereis* searches for sources, by a whitespace-separated list of directories.
  93
  94 *-f*::
  95 Terminates the directory list and signals the start of filenames. It _must_ be used when any of the *-B*, *-M*, or *-S* options is used.
  96
  97 *-l*::
  98 Output the list of effective lookup paths that *whereis* is using. When none of *-B*, *-M*, or *-S* is specified, the option will output the hard-coded paths that the command was able to find on the system.
  99
 100 *-g*::
 101 Interpret the next names as a *glob(7)* patterns. *whereis* always compares only filenames (aka basename) and never complete path. Using directory names in the pattern has no effect. Don’t forget that the shell interprets the pattern when specified on the command line without quotes. It’s necessary to use quotes for the _name_, for example:
 102 ____
 103   whereis -g 'find*'
 104 ____
 105
 106 include::man-common/help-version.adoc[]
 107
 108 == FILE SEARCH PATHS
 109
 110 By default *whereis* tries to find files from hard-coded paths, which are defined with glob patterns. The command attempts to use the contents of *$PATH* and *$MANPATH* environment variables as default search path. The easiest way to know what paths are in use is to add the *-l* listing option. Effects of the *-B*, *-M*, and *-S* are displayed with *-l*.
 111
 112 == ENVIRONMENT
 113
 114 *WHEREIS_DEBUG*=all::
 115 enables debug output.
 116
 117 == EXAMPLES
 118
 119 To find all files in _/usr/bin_ which are not documented in _/usr/man/man1_ or have no source in _/usr/src_:
 120 ____
 121 *cd /usr/bin* +
 122 *whereis -u -ms -M /usr/man/man1 -S /usr/src -f **
 123 ____
 124 include::man-common/bugreports.adoc[]
 125
 126 include::man-common/footer.adoc[]
 127
 128 ifdef::translation[]
 129 include::man-common/translation.adoc[]
 130 endif::[]