LINFO

The whereis Command



The whereis command is used to locate the binary, the source code and the online manual page for any specified program.

A binary is an executable (i.e., ready to run) form of a program. Source code is the original form of a program as written by a human using a programming language and before it has been converted by a compiler into a binary. The online manual pages, commonly referred to as man pages, are normally accessed using the man command.

whereis's basic syntax is

whereis [option(s)] program_name(s)

When used without any options, which is most commonly the case, whereis attempts to supply the absolute path names (i.e., the path to the root directory) for the binary, source code and man page for every program name (including command names, which are generally the same as program names) that is supplied to it as an argument (i.e., input). Any number of names can be accepted as arguments, and the results for each will be returned on a separate line.

Thus, for example, the following would be used to attempt to find the locations of the executable, source code and man page for the ls command (which is used to list the contents of any specified directory):

whereis ls

Although whereis ideally returns three pieces of information for each argument, in reality it often returns fewer and sometimes returns more. For example, it will not return a location for source code for a program on a computer for which the source code has not been installed (which is common when programs are installed in precompiled form during installation of the operating system). Likewise, there may be no man pages for some commands, or there may be more than one.

For some commands it might be the case that no executable is returned. Examples include alias and umask. This is presumably because no separate executables with these names exist and such commands are built directly into the shell (i.e., the program that executes commands typed in by a user and displays their results).

If an executable, source code or man page file exists on a computer but has not installed in a standard location, no result will be returned for it. This is because whereis only searches in such locations. An example is the situation in which a user has installed a program in its home directory (i.e., the directory which contains configuration files, programs and data specific to that user) rather than in directories that are accessible to all users.

In the event that nothing is found for one or more of the three types of information for which whereis searches for each argument, no error message or other notification is provided. If multiple results are found, whereis returns all of them.

In some situations, whereis might return only a single entry for some commands. This is true in the case of the spell command (which, as its name implies, is used to check the spelling of text files), at least on some systems, as can be seen by running the following:

whereis spell

Several options are available to limit the type of results returned by whereis (as is the case with the wc command, which by default counts the number of lines, words and characters that are contained in text). The -b option tells it to search only for binaries. The -m option tells it to search only for man pages. The -s option tells it to search only for sources. Thus, for example, the following could be used to search for only the binaries and source code for the whoami command (which reports the owner of the current login session):

whereis -b whoami

As is generally (but not always) the case with single-letter options for shell programs, these options can be used together in any combination and any order. The order in which the results are displayed is not affected by the order in which the options are used.






Created July 28, 2006.
Copyright © 2006 The Linux Information Project. All Rights Reserved.