share/man/man1/hash.1

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
  45 .\" Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH HASH 1 "Jul 17, 2002"
  48 .SH NAME
  49 hash, rehash, unhash, hashstat \- evaluate the internal hash table of the
  50 contents of directories
  51 .SH SYNOPSIS
  52 .LP
  53 .nf
  54 \fB/usr/bin/hash\fR [\fIutility\fR]
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fB/usr/bin/hash\fR [\fB-r\fR]
  60 .fi
  61
  62 .SS "sh"
  63 .LP
  64 .nf
  65 \fBhash\fR [\fB-r\fR] [\fIname\fR]...
  66 .fi
  67
  68 .SS "csh"
  69 .LP
  70 .nf
  71 \fBrehash\fR
  72 .fi
  73
  74 .LP
  75 .nf
  76 \fBunhash\fR
  77 .fi
  78
  79 .LP
  80 .nf
  81 \fBhashstat\fR
  82 .fi
  83
  84 .SS "ksh"
  85 .LP
  86 .nf
  87 \fBhash\fR [\fIname\fR]...
  88 .fi
  89
  90 .LP
  91 .nf
  92 \fBhash\fR [\fB-r\fR]
  93 .fi
  94
  95 .SH DESCRIPTION
  96 .SS "/usr/bin/hash"
  97 .sp
  98 .LP
  99 The \fB/usr/bin/hash\fR utility affects the way the current shell environment
 100 remembers the locations of utilities found.  Depending on the arguments
 101 specified, it adds utility locations to its list of remembered locations or it
 102 purges the contents of the list. When no arguments are specified, it reports on
 103 the contents of the list. The \fB-r\fR option causes the shell to forget all
 104 remembered locations.
 105 .sp
 106 .LP
 107 Utilities provided as built-ins to the shell are not reported by \fBhash\fR.
 108 .SS "sh"
 109 .sp
 110 .LP
 111 For each \fIname\fR, the location in the search path of the command specified
 112 by \fIname\fR is determined and remembered by the shell. The \fB-r\fR option to
 113 the \fBhash\fR built-in causes the shell to forget all remembered locations. If
 114 no arguments are given, \fBhash\fR provides information about remembered
 115 commands. The \fIHits\fR column of output is the number of times a command has
 116 been invoked by the shell process. The \fICost\fR column of output is a measure
 117 of the work required to locate a command in the search path. If a command is
 118 found in a "relative" directory in the search path, after changing to that
 119 directory, the stored location of that command is recalculated. Commands for
 120 which this will be done are indicated by an asterisk (\fB*\fR) adjacent to the
 121 \fIHits\fR information. \fICost\fR will be incremented when the recalculation
 122 is done.
 123 .SS "csh"
 124 .sp
 125 .LP
 126 \fBrehash\fR recomputes the internal hash table of the contents of directories
 127 listed in the \fBpath\fR environmental variable to account for new commands
 128 added.
 129 .sp
 130 .LP
 131 \fBunhash\fR disables the internal hash table.
 132 .sp
 133 .LP
 134 \fBhashstat\fR prints a statistics line indicating how effective the internal
 135 hash table has been at locating commands (and avoiding \fBexec\fRs). An
 136 \fBexec\fR is attempted for each component of the \fIpath\fR where the hash
 137 function indicates a possible hit and in each component that does not begin
 138 with a '\|/\|'.
 139 .SS "ksh"
 140 .sp
 141 .LP
 142 For each \fIname\fR, the location in the search path of the command specified
 143 by \fIname\fR is determined and remembered by the shell. The \fB-r\fR option to
 144 the \fBhash\fR built-in causes the shell to forget all remembered locations. If
 145 no arguments are given, \fBhash\fR provides information about remembered
 146 commands.
 147 .SH OPERANDS
 148 .sp
 149 .LP
 150 The following operand is supported by \fBhash\fR:
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fIutility\fR \fR
 155 .ad
 156 .RS 12n
 157 The name of a utility to be searched for and added to the list of remembered
 158 locations.
 159 .RE
 160
 161 .SH OUTPUT
 162 .sp
 163 .LP
 164 The standard output of \fBhash\fR is used when no arguments are specified. Its
 165 format is unspecified, but includes the pathname of each utility in the list of
 166 remembered locations for the current shell environment. This list consists of
 167 those utilities named in previous \fBhash\fR invocations that have been
 168 invoked, and may contain those invoked and found through the normal command
 169 search process.
 170 .SH ENVIRONMENT VARIABLES
 171 .sp
 172 .LP
 173 See \fBenviron\fR(5) for descriptions of the following environment variables
 174 that affect the execution of \fBhash\fR: \fBLANG\fR, \fBLC_ALL\fR,
 175 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBPATH\fR \fR
 180 .ad
 181 .RS 9n
 182 Determine the location of \fIutility\fR.
 183 .RE
 184
 185 .SH EXIT STATUS
 186 .sp
 187 .LP
 188 The following exit values are returned by \fBhash\fR:
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fB0\fR \fR
 193 .ad
 194 .RS 7n
 195 Successful completion.
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fB>0\fR \fR
 202 .ad
 203 .RS 7n
 204 An error occurred.
 205 .RE
 206
 207 .SH ATTRIBUTES
 208 .sp
 209 .LP
 210 See \fBattributes\fR(5) for descriptions of the following attributes:
 211 .sp
 212
 213 .sp
 214 .TS
 215 box;
 216 c | c
 217 l | l .
 218 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 219 _
 220 Interface Stability     Standard
 221 .TE
 222
 223 .SH SEE ALSO
 224 .sp
 225 .LP
 226 \fBcsh\fR(1), \fBksh\fR(1), \fBsh\fR(1), \fBattributes\fR(5), \fBenviron\fR(5),
 227 \fBstandards\fR(5)