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 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures 46 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved 47 .\" 48 .TH CD 1 "Apr 8, 2008" 49 .SH NAME 50 cd, chdir, pushd, popd, dirs \- change working directory 51 .SH SYNOPSIS 52 .LP 53 .nf 54 \fB/usr/bin/cd\fR [\fIdirectory\fR] 55 .fi 56 57 .SS "sh" 58 .LP 59 .nf 60 \fBcd\fR [\fIargument\fR] 61 .fi 62 63 .LP 64 .nf 65 \fBchdir\fR [\fIargument\fR] 66 .fi 67 68 .SS "csh" 69 .LP 70 .nf 71 \fBcd\fR [\fIdir\fR] 72 .fi 73 74 .LP 75 .nf 76 \fBchdir\fR [\fIdir\fR] 77 .fi 78 79 .LP 80 .nf 81 \fBpushd\fR [\fB+\fR\fIn\fR | \fIdir\fR] 82 .fi 83 84 .LP 85 .nf 86 \fBpopd\fR [\fB+\fR\fIn\fR] 87 .fi 88 89 .LP 90 .nf 91 \fBdirs\fR [\fB-l\fR] 92 .fi 93 94 .SS "ksh, ksh93" 95 .LP 96 .nf 97 \fBcd\fR [\fB-L\fR] [\fB-P\fR] [\fIarg\fR] 98 .fi 99 100 .LP 101 .nf 102 \fBcd\fR \fIold\fR \fInew\fR 103 .fi 104 105 .SH DESCRIPTION 106 .SS "/usr/bin/cd" 107 .sp 108 .LP 109 The \fB/usr/bin/cd\fR utility changes the current directory in the context of 110 the \fBcd\fR utility only. This is in contrast to the version built into the 111 shell. \fB/usr/bin/cd\fR has no effect on the invoking process but can be used 112 to determine whether or not a given directory can be set as the current 113 directory. 114 .SS "sh" 115 .sp 116 .LP 117 The Bourne shell built-in \fBcd\fR changes the current directory to 118 \fIargument\fR. The shell parameter \fBHOME\fR is the default \fIargument\fR. 119 The shell parameter \fBCDPATH\fR defines the search path for the directory 120 containing \fIargument\fR. Alternative directory names are separated by a colon 121 (\fB:\fR). The default path is \fB<null>\fR (specifying the current directory). 122 The current directory is specified by a null path name, which can appear 123 immediately after the equal sign or between the colon delimiters anywhere else 124 in the path list. If \fIargument\fR begins with `\fB/\fR', `\fB\&.\fR', or 125 `\fB\&.\|.\fR', the search path is not used. Otherwise, each directory in the 126 path is searched for \fIargument\fR. \fBcd\fR must have execute (search) 127 permission in \fIargument\fR. Because a new process is created to execute each 128 command, \fBcd\fR would be ineffective if it were written as a normal command; 129 therefore, it is recognized by and is internal to the shell. (See \fBpwd\fR(1), 130 \fBsh\fR(1), and \fBchdir\fR(2)). 131 .sp 132 .LP 133 \fBchdir\fR is just another way to call \fBcd\fR. 134 .SS "csh" 135 .sp 136 .LP 137 If \fIdir\fR is not specified, the C shell built-in \fBcd\fR uses the value of 138 shell parameter \fBHOME\fR as the new working directory. If \fIdir\fR specifies 139 a complete path starting with `\fB/\fR', `\fB\&.\fR', or `\fB\&.\|.\fR', 140 \fIdir\fR becomes the new working directory. If neither case applies, \fBcd\fR 141 tries to find the designated directory relative to one of the paths specified 142 by the \fBCDPATH\fR shell variable. \fBCDPATH\fR has the same syntax as, and 143 similar semantics to, the \fBPATH\fR shell variable. \fBcd\fR must have execute 144 (search) permission in \fIdir\fR. Because a new process is created to execute 145 each command, \fBcd\fR would be ineffective if it were written as a normal 146 command; therefore, it is recognized by and is internal to the C-shell. (See 147 \fBpwd\fR(1), \fBsh\fR(1), and \fBchdir\fR(2)). 148 .sp 149 .LP 150 \fBchdir\fR changes the shell's working directory to directory \fIdir\fR. If no 151 argument is given, change to the home directory of the user. If \fIdir\fR is a 152 relative pathname not found in the current directory, check for it in those 153 directories listed in the \fBcdpath\fR variable. If \fIdir\fR is the name of a 154 shell variable whose value starts with a \fB/\fR, change to the directory named 155 by that value. 156 .sp 157 .LP 158 \fBpushd\fR pushes a directory onto the directory stack. With no arguments, 159 exchange the top two elements. 160 .sp 161 .ne 2 162 .na 163 \fB\fB+\fR\fIn\fR\fR 164 .ad 165 .RS 7n 166 Rotate the \fIn\fR'th entry to the top of the stack and \fBcd\fR to it. 167 .RE 168 169 .sp 170 .ne 2 171 .na 172 \fB\fIdir\fR\fR 173 .ad 174 .RS 7n 175 Push the current working directory onto the stack and change to \fIdir\fR. 176 .RE 177 178 .sp 179 .LP 180 \fBpopd\fR pops the directory stack and \fBcd\fR to the new top directory. The 181 elements of the directory stack are numbered from 0 starting at the top. 182 .sp 183 .ne 2 184 .na 185 \fB\fB+\fR\fIn\fR\fR 186 .ad 187 .RS 6n 188 Discard the \fIn\fR'th entry in the stack. 189 .RE 190 191 .sp 192 .LP 193 \fBdirs\fR prints the directory stack, most recent to the left; the first 194 directory shown is the current directory. With the \fB-l\fR argument, produce 195 an unabbreviated printout; use of the \fB~\fR notation is suppressed. 196 .SS "ksh, ksh93" 197 .sp 198 .LP 199 The Korn shell built-in \fBcd\fR command can be in either of two forms. In the 200 first form it changes the current directory to \fIarg\fR. If \fIarg\fR is 201 \fB\(mi\fR the directory is changed to the previous directory. The shell 202 variable \fBHOME\fR is the default \fIarg\fR. The environment variable 203 \fBPWD\fR is set to the current directory. If the \fBPWD\fR is changed, the 204 \fBOLDPWD\fR environment variable shall also be changed to the value of the old 205 working directory, that is, the current working directory immediately prior to 206 the call to change directory (\fBcd\fR). The shell variable \fBCDPATH\fR 207 defines the search path for the directory containing \fIarg\fR. Alternative 208 directory names are separated by a colon (\fB:\fR). The default path is 209 \fBnull\fR (specifying the current directory). The current directory is 210 specified by a null path name, which can appear immediately after the equal 211 sign or between the colon delimiters anywhere else in the path list. If 212 \fIarg\fR begins with a `\fB/\fR', `\fB\&.\fR', or `\fB\&.\|.\fR', then the 213 search path is not used. Otherwise, each directory in the path is searched for 214 \fIarg\fR. If unsuccessful, \fBcd\fR attempts to change directories to the 215 pathname formed by the concatenation of the value of PWD, a slash character, 216 and arg. 217 .sp 218 .ne 2 219 .na 220 \fB\fB-L\fR\fR 221 .ad 222 .RS 6n 223 Handles the operation dot-dot (\fB\&..\fR) logically. Symbolic link components 224 are \fBnot\fR resolved before dot-dot components are processed. 225 .RE 226 227 .sp 228 .ne 2 229 .na 230 \fB\fB-P\fR\fR 231 .ad 232 .RS 6n 233 Handles the operand dot-dot physically. Symbolic link components \fBare\fR 234 resolved before dot-dot components are processed. 235 .RE 236 237 .sp 238 .LP 239 If both \fB-L\fR and \fB-P\fR options are specified, the last option to be 240 invoked is used and the other is ignored. If neither \fB-L\fR nor \fB-P\fR is 241 specified, the operand is handled dot-dot logically. 242 .sp 243 .LP 244 The second form of \fBcd\fR substitutes the string \fInew\fR for the string 245 \fIold\fR in the current directory name, \fBPWD\fR and tries to change to this 246 new directory. 247 .sp 248 .LP 249 The \fBcd\fR command cannot be executed by \fBrksh\fR. Because a new process is 250 created to execute each command, \fBcd\fR would be ineffective if it were 251 written as a normal command; therefore, it is recognized by and is internal to 252 the Korn shell. (See \fBpwd\fR(1), \fBsh\fR(1), and \fBchdir\fR(2)). 253 .SH OPERANDS 254 .sp 255 .LP 256 The following operands are supported: 257 .sp 258 .ne 2 259 .na 260 \fB\fIdirectory\fR\fR 261 .ad 262 .RS 13n 263 An absolute or relative pathname of the directory that becomes the new working 264 directory. The interpretation of a relative pathname by \fBcd\fR depends on the 265 \fBCDPATH\fR environment variable. 266 .RE 267 268 .SH OUTPUT 269 .sp 270 .LP 271 If a non-empty directory name from \fBCDPATH\fR is used, an absolute pathname 272 of the new working directory is written to the standard output as follows: 273 .sp 274 .LP 275 \fB"%s\en"\fR, <\fInew directory\fR> 276 .sp 277 .LP 278 Otherwise, there is no output. 279 .SH ENVIRONMENT VARIABLES 280 .sp 281 .LP 282 See \fBenviron\fR(5) for descriptions of the following environment variables 283 that affect the execution of \fBcd\fR: \fBLANG\fR, \fBLC_ALL\fR, 284 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR. 285 .sp 286 .ne 2 287 .na 288 \fB\fBCDPATH\fR\fR 289 .ad 290 .RS 10n 291 A colon-separated list of pathnames that refer to directories. If the 292 \fIdirectory\fR operand does not begin with a slash \fB(\fR \fB/\fR \fB)\fR 293 character, and the first component is not dot or dot-dot, \fBcd\fR searches for 294 \fIdirectory\fR relative to each directory named in the \fBCDPATH\fR variable, 295 in the order listed. The new working directory sets to the first matching 296 directory found. An empty string in place of a directory pathname represents 297 the current directory. If \fBCDPATH\fR is not set, it is treated as if it were 298 an empty string. 299 .RE 300 301 .sp 302 .ne 2 303 .na 304 \fB\fBHOME\fR\fR 305 .ad 306 .RS 10n 307 The name of the home directory, used when no \fIdirectory\fR operand is 308 specified. 309 .RE 310 311 .sp 312 .ne 2 313 .na 314 \fB\fBOLDPWD\fR\fR 315 .ad 316 .RS 10n 317 A pathname of the previous working directory, used by \fBcd-\fR. 318 .RE 319 320 .sp 321 .ne 2 322 .na 323 \fB\fBPWD\fR\fR 324 .ad 325 .RS 10n 326 A pathname of the current working directory, set by \fBcd\fR after it has 327 changed to that directory. 328 .RE 329 330 .SH EXIT STATUS 331 .sp 332 .LP 333 The following exit values are returned by \fBcd\fR: 334 .sp 335 .ne 2 336 .na 337 \fB\fB0\fR\fR 338 .ad 339 .RS 6n 340 The directory was successfully changed. 341 .RE 342 343 .sp 344 .ne 2 345 .na 346 \fB\fB>0\fR\fR 347 .ad 348 .RS 6n 349 An error occurred. 350 .RE 351 352 .SH ATTRIBUTES 353 .sp 354 .LP 355 See \fBattributes\fR(5) for descriptions of the following attributes: 356 .SS "csh, ksh, sh" 357 .sp 358 359 .sp 360 .TS 361 box; 362 c | c 363 l | l . 364 ATTRIBUTE TYPE ATTRIBUTE VALUE 365 _ 366 Interface Stability Committed 367 _ 368 Standard See \fBstandards\fR(5). 369 .TE 370 371 .SS "ksh93" 372 .sp 373 374 .sp 375 .TS 376 box; 377 c | c 378 l | l . 379 ATTRIBUTE TYPE ATTRIBUTE VALUE 380 _ 381 Interface Stability Uncommitted 382 .TE 383 384 .SH SEE ALSO 385 .sp 386 .LP 387 \fBcsh\fR(1), \fBksh\fR(1), \fBksh93\fR(1), \fBpwd\fR(1), \fBsh\fR(1), 388 \fBchdir\fR(2), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)