1CD(1P) POSIX Programmer's Manual CD(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 cd — change the working directory
13
15 cd [-L|-P] [directory]
16 cd -
18
20 The cd utility shall change the working directory of the current shell
21 execution environment (see Section 2.12, Shell Execution Environment)
22 by executing the following steps in sequence. (In the following steps,
23 the symbol curpath represents an intermediate value used to simplify
24 the description of the algorithm used by cd. There is no requirement
25 that curpath be made visible to the application.)
26 1. If no directory operand is given and the HOME environment variable
28 is empty or undefined, the default behavior is implementation-
29 defined and no further steps shall be taken.
30 2. If no directory operand is given and the HOME environment variable
32 is set to a non-empty value, the cd utility shall behave as if the
33 directory named in the HOME environment variable was specified as
34 the directory operand.
35 3. If the directory operand begins with a <slash> character, set cur‐
37 path to the operand and proceed to step 7.
38 4. If the first component of the directory operand is dot or dot-dot,
40 proceed to step 6.
41 5. Starting with the first pathname in the <colon>-separated pathnames
43 of CDPATH (see the ENVIRONMENT VARIABLES section) if the pathname
44 is non-null, test if the concatenation of that pathname, a <slash>
45 character if that pathname did not end with a <slash> character,
46 and the directory operand names a directory. If the pathname is
47 null, test if the concatenation of dot, a <slash> character, and
48 the operand names a directory. In either case, if the resulting
49 string names an existing directory, set curpath to that string and
50 proceed to step 7. Otherwise, repeat this step with the next path‐
51 name in CDPATH until all pathnames have been tested.
52 6. Set curpath to the directory operand.
54 7. If the -P option is in effect, proceed to step 10. If curpath does
56 not begin with a <slash> character, set curpath to the string
57 formed by the concatenation of the value of PWD, a <slash> charac‐
58 ter if the value of PWD did not end with a <slash> character, and
59 curpath.
60 8. The curpath value shall then be converted to canonical form as fol‐
62 lows, considering each component from beginning to end, in
63 sequence:
64 a. Dot components and any <slash> characters that separate them
66 from the next component shall be deleted.
67 b. For each dot-dot component, if there is a preceding component
69 and it is neither root nor dot-dot, then:
70 i. If the preceding component does not refer (in the context
72 of pathname resolution with symbolic links followed) to a
73 directory, then the cd utility shall display an appropri‐
74 ate error message and no further steps shall be taken.
75 ii. The preceding component, all <slash> characters separating
77 the preceding component from dot-dot, dot-dot, and all
78 <slash> characters separating dot-dot from the following
79 component (if any) shall be deleted.
80 c. An implementation may further simplify curpath by removing any
82 trailing <slash> characters that are not also leading <slash>
83 characters, replacing multiple non-leading consecutive <slash>
84 characters with a single <slash>, and replacing three or more
85 leading <slash> characters with a single <slash>. If, as a
86 result of this canonicalization, the curpath variable is null,
87 no further steps shall be taken.
88 9. If curpath is longer than {PATH_MAX} bytes (including the terminat‐
90 ing null) and the directory operand was not longer than {PATH_MAX}
91 bytes (including the terminating null), then curpath shall be con‐
92 verted from an absolute pathname to an equivalent relative pathname
93 if possible. This conversion shall always be considered possible if
94 the value of PWD, with a trailing <slash> added if it does not
95 already have one, is an initial substring of curpath. Whether or
96 not it is considered possible under other circumstances is unspeci‐
97 fied. Implementations may also apply this conversion if curpath is
98 not longer than {PATH_MAX} bytes or the directory operand was
99 longer than {PATH_MAX} bytes.
100 10. The cd utility shall then perform actions equivalent to the chdir()
102 function called with curpath as the path argument. If these actions
103 fail for any reason, the cd utility shall display an appropriate
104 error message and the remainder of this step shall not be executed.
105 If the -P option is not in effect, the PWD environment variable
106 shall be set to the value that curpath had on entry to step 9
107 (i.e., before conversion to a relative pathname). If the -P option
108 is in effect, the PWD environment variable shall be set to the
109 string that would be output by pwd -P. If there is insufficient
110 permission on the new directory, or on any parent of that direc‐
111 tory, to determine the current working directory, the value of the
112 PWD environment variable is unspecified.
113 If, during the execution of the above steps, the PWD environment vari‐
115 able is set, the OLDPWD environment variable shall also be set to the
116 value of the old working directory (that is the current working direc‐
117 tory immediately prior to the call to cd).
118
120 The cd utility shall conform to the Base Definitions volume of
121 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
122 The following options shall be supported by the implementation:
124 -L Handle the operand dot-dot logically; symbolic link compo‐
126 nents shall not be resolved before dot-dot components are
127 processed (see steps 8. and 9. in the DESCRIPTION).
128 -P Handle the operand dot-dot physically; symbolic link compo‐
130 nents shall be resolved before dot-dot components are pro‐
131 cessed (see step 7. in the DESCRIPTION).
132 If both -L and -P options are specified, the last of these options
134 shall be used and all others ignored. If neither -L nor -P is speci‐
135 fied, the operand shall be handled dot-dot logically; see the DESCRIP‐
136 TION.
137
139 The following operands shall be supported:
140 directory An absolute or relative pathname of the directory that shall
142 become the new working directory. The interpretation of a
143 relative pathname by cd depends on the -L option and the
144 CDPATH and PWD environment variables. If directory is an
145 empty string, the results are unspecified.
146 - When a <hyphen-minus> is used as the operand, this shall be
148 equivalent to the command:
149 cd "$OLDPWD" && pwd
152 which changes to the previous working directory and then
154 writes its name.
155
157 Not used.
158
160 None.
161
163 The following environment variables shall affect the execution of cd:
164 CDPATH A <colon>-separated list of pathnames that refer to directo‐
166 ries. The cd utility shall use this list in its attempt to
167 change the directory, as described in the DESCRIPTION. An
168 empty string in place of a directory pathname represents the
169 current directory. If CDPATH is not set, it shall be treated
170 as if it were an empty string.
171 HOME The name of the directory, used when no directory operand is
173 specified.
174 LANG Provide a default value for the internationalization vari‐
176 ables that are unset or null. (See the Base Definitions vol‐
177 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
178 ables for the precedence of internationalization variables
179 used to determine the values of locale categories.)
180 LC_ALL If set to a non-empty string value, override the values of
182 all the other internationalization variables.
183 LC_CTYPE Determine the locale for the interpretation of sequences of
185 bytes of text data as characters (for example, single-byte as
186 opposed to multi-byte characters in arguments).
187 LC_MESSAGES
189 Determine the locale that should be used to affect the format
190 and contents of diagnostic messages written to standard
191 error.
192 NLSPATH Determine the location of message catalogs for the processing
194 of LC_MESSAGES.
195 OLDPWD A pathname of the previous working directory, used by cd -.
197 PWD This variable shall be set as specified in the DESCRIPTION.
199 If an application sets or unsets the value of PWD, the behav‐
200 ior of cd is unspecified.
201
203 Default.
204
206 If a non-empty directory name from CDPATH is used, or if cd - is used,
207 an absolute pathname of the new working directory shall be written to
208 the standard output as follows:
209 "%s\n", <new directory>
212 Otherwise, there shall be no output.
214
216 The standard error shall be used only for diagnostic messages.
217
219 None.
220
222 None.
223
225 The following exit values shall be returned:
226 0 The directory was successfully changed.
228 >0 An error occurred.
230
232 The working directory shall remain unchanged.
233 The following sections are informative.
235
237 Since cd affects the current shell execution environment, it is always
238 provided as a shell regular built-in. If it is called in a subshell or
239 separate utility execution environment, such as one of the following:
240 (cd /tmp)
243 nohup cd
244 find . -exec cd {} \;
245 it does not affect the working directory of the caller's environment.
247 The user must have execute (search) permission in directory in order to
249 change to it.
250
252 The following template can be used to perform processing in the direc‐
253 tory specified by location and end up in the current working directory
254 in use before the first cd command was issued:
255 cd location
258 if [ $? -ne 0 ]
259 then
260 print error message
261 exit 1
262 fi
263 ... do whatever is desired as long as the OLDPWD environment variable
264 is not modified
265 cd -
266
268 The use of the CDPATH was introduced in the System V shell. Its use is
269 analogous to the use of the PATH variable in the shell. The BSD C shell
270 used a shell parameter cdpath for this purpose.
271 A common extension when HOME is undefined is to get the login directory
273 from the user database for the invoking user. This does not occur on
274 System V implementations.
275 Some historical shells, such as the KornShell, took special actions
277 when the directory name contained a dot-dot component, selecting the
278 logical parent of the directory, rather than the actual parent direc‐
279 tory; that is, it moved up one level toward the '/' in the pathname,
280 remembering what the user typed, rather than performing the equivalent
281 of:
282 chdir("..");
285 In such a shell, the following commands would not necessarily produce
287 equivalent output for all directories:
288 cd .. && ls ls ..
291 This behavior is now the default. It is not consistent with the defini‐
293 tion of dot-dot in most historical practice; that is, while this behav‐
294 ior has been optionally available in the KornShell, other shells have
295 historically not supported this functionality. The logical pathname is
296 stored in the PWD environment variable when the cd utility completes
297 and this value is used to construct the next directory name if cd is
298 invoked with the -L option.
299
301 None.
302
304 Section 2.12, Shell Execution Environment, pwd
305 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
307 Variables, Section 12.2, Utility Syntax Guidelines
308 The System Interfaces volume of POSIX.1‐2017, chdir()
310
312 Portions of this text are reprinted and reproduced in electronic form
313 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
314 table Operating System Interface (POSIX), The Open Group Base Specifi‐
315 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
316 Electrical and Electronics Engineers, Inc and The Open Group. In the
317 event of any discrepancy between this version and the original IEEE and
318 The Open Group Standard, the original IEEE and The Open Group Standard
319 is the referee document. The original Standard can be obtained online
320 at http://www.opengroup.org/unix/online.html .
321 Any typographical or formatting errors that appear in this page are
323 most likely to have been introduced during the conversion of the source
324 files to man page format. To report such errors, see https://www.ker‐
325 nel.org/doc/man-pages/reporting_bugs.html .
326IEEE/The Open Group 2017 CD(1P)