hash - remember or report utility locations

The POSIX shell built-in hash has two functions:

• it can write the contents of the hash table on standard output or enter the specified command in the hash table (Format 1),

• it can delete the contents of the hash table (Format 2).

Each shell maintains its own hash table, in which it enters all commands that are invoked under their basic file names (basenames). Whenever you invoke a command under its basename, the shell first searches the hash table for your command. This accelerates the search process. If the command is not yet in the hash table of the current shell, it is entered there.

When you start a subshell, its hash table is empty. When you terminate the subshell, the parent shell returns with its own hash table, and the hash table of the subshell is deleted.

Syntax

Format 1:	hash[ name...]
Format 2:	hash -r

Display or extend hash table

Format 1:

hash[ name...]

name

Basename of a command, an executable shell script, or an executable program. The shell searches for this file by examining the contents of the PATH variable. When the file is found, the following information is passed to hash:

• the appropriate relative path name in the form ./name if the current directory is assigned to the PATH variable and contains name, or

• the absolute path name.

The hash command enters this path name into the hash table. If name is not present in any of the directories assigned to the PATH variable, an error message is issued.

The following cannot be specified for name:

• shell scripts for which you have no execute permission.

• commands with a name that includes a slash. This means that you cannot enter absolute or relative path names.

• shell built-ins, since they are subroutines of sh and thus do not have names that represent executable files.

By the same token, executable shell scripts and commands are not entered in the hash table unless they are invoked under their basenames.

name not specified:
The hash command writes the contents of the hash table on the standard output. The output can, for example, be structured as follows:

ls=/usr/bin/ls
cat=/usr/bin/cat
chmod=/usr/bin/chmod 

Delete hash table

Format 2:

hash -r

-r

Deletes the contents of the hash table.

If you modify the value of the PATH variable, the contents of the hash table are automatically deleted. When you terminate the current shell, the hash table associated with this shell is also deleted.

You should always delete the contents of the hash table in the current shell in the following circumstances:

You have created an executable file in a directory dira whose path name is assigned to the PATH variable. Some other directory dirb, also specified in PATH, already contains an identically named command file which already appears in the current hash table. In this case the shell will always execute the older command, even if its directory (dirb) comes after the first one (dira) in the PATH variable.

Deleting the hash table with hash -r will cause the shell to execute the first command it finds the next time either of these commands is invoked. In other words, the sequence of the entries in the PATH variable will be the determining factor. The path name of the first command found is now entered into the hash table, i.e. your command will always be executed from now on when you invoke it under its basename.

Error

name : not found
This error message may be produced for any of the following reasons:

• name is not contained in any of the directories whose respective paths have been entered in the PATH variable.

• name is actually contained in one of these directories, but is not executable.

• name is a shell built-in or a shell function.

Variable

PATH

Search path of the shell

Locale

The following environment variables affect the execution of hash:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files), the classification of characters as upper- to lower-case, and the mapping of characters from one case to the other.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example 1

Display the contents of the hash table:

$ echo $PATH
/bin:/usr/bin:.

$ hash

cat=/usr/bin/cat

ls=/usr/bin/ls

Example 2

Add a command to the hash table:

$ hash cat

$ hash
cat=/usr/bin/cat

The command /usr/bin/cat is now a new entry in the hash table.

Example 3

The following excerpt from a session demonstrates when the hash table is cleared:

$ hash

cat=/usr/bin/cat

ls=/usr/bin/ls

$ sh

$ hash

$ cp <file1> <file2>
...

$ ls

...

$ hash

cp=/usr/bin/cp

ls=/usr/bin/ls

$ exit

$ hash

cat=/usr/bin/cat

ls=/usr/bin/ls

The hash table in the new subshell is empty. When the subshell is terminated, the hash table of the parent shell becomes valid again, while that of the subshell is deleted.