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