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
13 cd — change the working directory
14
16 cd [−L|−P] [directory]
17 cd −
19
21 The cd utility shall change the working directory of the current shell
22 execution environment (see Section 2.12, Shell Execution Environment)
23 by executing the following steps in sequence. (In the following steps,
24 the symbol curpath represents an intermediate value used to simplify
25 the description of the algorithm used by cd. There is no requirement
26 that curpath be made visible to the application.)
27 1. If no directory operand is given and the HOME environment variable
29 is empty or undefined, the default behavior is implementation-
30 defined and no further steps shall be taken.
31 2. If no directory operand is given and the HOME environment variable
33 is set to a non-empty value, the cd utility shall behave as if the
34 directory named in the HOME environment variable was specified as
35 the directory operand.
36 3. If the directory operand begins with a <slash> character, set cur‐
38 path to the operand and proceed to step 7.
39 4. If the first component of the directory operand is dot or dot-dot,
41 proceed to step 6.
42 5. Starting with the first pathname in the <colon>-separated pathnames
44 of CDPATH (see the ENVIRONMENT VARIABLES section) if the pathname
45 is non-null, test if the concatenation of that pathname, a <slash>
46 character if that pathname did not end with a <slash> character,
47 and the directory operand names a directory. If the pathname is
48 null, test if the concatenation of dot, a <slash> character, and
49 the operand names a directory. In either case, if the resulting
50 string names an existing directory, set curpath to that string and
51 proceed to step 7. Otherwise, repeat this step with the next path‐
52 name in CDPATH until all pathnames have been tested.
53 6. Set curpath to the directory operand.
55 7. If the −P option is in effect, proceed to step 10. If curpath does
57 not begin with a <slash> character, set curpath to the string
58 formed by the concatenation of the value of PWD, a <slash> charac‐
59 ter if the value of PWD did not end with a <slash> character, and
60 curpath.
61 8. The curpath value shall then be converted to canonical form as fol‐
63 lows, considering each component from beginning to end, in
64 sequence:
65 a. Dot components and any <slash> characters that separate them
67 from the next component shall be deleted.
68 b. For each dot-dot component, if there is a preceding component
70 and it is neither root nor dot-dot, then:
71 i. If the preceding component does not refer (in the context
73 of pathname resolution with symbolic links followed) to a
74 directory, then the cd utility shall display an appropri‐
75 ate error message and no further steps shall be taken.
76 ii. The preceding component, all <slash> characters separating
78 the preceding component from dot-dot, dot-dot, and all
79 <slash> characters separating dot-dot from the following
80 component (if any) shall be deleted.
81 c. An implementation may further simplify curpath by removing any
83 trailing <slash> characters that are not also leading <slash>
84 characters, replacing multiple non-leading consecutive <slash>
85 characters with a single <slash>, and replacing three or more
86 leading <slash> characters with a single <slash>. If, as a
87 result of this canonicalization, the curpath variable is null,
88 no further steps shall be taken.
89 9. If curpath is longer than {PATH_MAX} bytes (including the terminat‐
91 ing null) and the directory operand was not longer than {PATH_MAX}
92 bytes (including the terminating null), then curpath shall be con‐
93 verted from an absolute pathname to an equivalent relative pathname
94 if possible. This conversion shall always be considered possible if
95 the value of PWD, with a trailing <slash> added if it does not
96 already have one, is an initial substring of curpath. Whether or
97 not it is considered possible under other circumstances is unspeci‐
98 fied. Implementations may also apply this conversion if curpath is
99 not longer than {PATH_MAX} bytes or the directory operand was
100 longer than {PATH_MAX} bytes.
101 10. The cd utility shall then perform actions equivalent to the chdir()
103 function called with curpath as the path argument. If these actions
104 fail for any reason, the cd utility shall display an appropriate
105 error message and the remainder of this step shall not be executed.
106 If the −P option is not in effect, the PWD environment variable
107 shall be set to the value that curpath had on entry to step 9
108 (i.e., before conversion to a relative pathname). If the −P option
109 is in effect, the PWD environment variable shall be set to the
110 string that would be output by pwd −P. If there is insufficient
111 permission on the new directory, or on any parent of that direc‐
112 tory, to determine the current working directory, the value of the
113 PWD environment variable is unspecified.
114 If, during the execution of the above steps, the PWD environment vari‐
116 able is set, the OLDPWD environment variable shall also be set to the
117 value of the old working directory (that is the current working direc‐
118 tory immediately prior to the call to cd).
119
121 The cd utility shall conform to the Base Definitions volume of
122 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
123 The following options shall be supported by the implementation:
125 −L Handle the operand dot-dot logically; symbolic link compo‐
127 nents shall not be resolved before dot-dot components are
128 processed (see steps 8. and 9. in the DESCRIPTION).
129 −P Handle the operand dot-dot physically; symbolic link compo‐
131 nents shall be resolved before dot-dot components are pro‐
132 cessed (see step 7. in the DESCRIPTION).
133 If both −L and −P options are specified, the last of these options
135 shall be used and all others ignored. If neither −L nor −P is speci‐
136 fied, the operand shall be handled dot-dot logically; see the DESCRIP‐
137 TION.
138
140 The following operands shall be supported:
141 directory An absolute or relative pathname of the directory that shall
143 become the new working directory. The interpretation of a
144 relative pathname by cd depends on the −L option and the
145 CDPATH and PWD environment variables. If directory is an
146 empty string, the results are unspecified.
147 − When a <hyphen> is used as the operand, this shall be equiva‐
149 lent to the command:
150 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‐2008, 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>
211 Otherwise, there shall be no output.
213
215 The standard error shall be used only for diagnostic messages.
216
218 None.
219
221 None.
222
224 The following exit values shall be returned:
225 0 The directory was successfully changed.
227 >0 An error occurred.
229
231 The working directory shall remain unchanged.
232 The following sections are informative.
234
236 Since cd affects the current shell execution environment, it is always
237 provided as a shell regular built-in. If it is called in a subshell or
238 separate utility execution environment, such as one of the following:
239 (cd /tmp)
241 nohup cd
242 find . −exec cd {} \;
243 it does not affect the working directory of the caller's environment.
245 The user must have execute (search) permission in directory in order to
247 change to it.
248
250 The following template can be used to perform processing in the direc‐
251 tory specified by location and end up in the current working directory
252 in use before the first cd command was issued:
253 cd location
255 if [ $? -ne 0 ]
256 then
257 print error message
258 exit 1
259 fi
260 ... do whatever is desired as long as the OLDPWD environment variable
261 is not modified
262 cd -
263
265 The use of the CDPATH was introduced in the System V shell. Its use is
266 analogous to the use of the PATH variable in the shell. The BSD C shell
267 used a shell parameter cdpath for this purpose.
268 A common extension when HOME is undefined is to get the login directory
270 from the user database for the invoking user. This does not occur on
271 System V implementations.
272 Some historical shells, such as the KornShell, took special actions
274 when the directory name contained a dot-dot component, selecting the
275 logical parent of the directory, rather than the actual parent direc‐
276 tory; that is, it moved up one level toward the '/' in the pathname,
277 remembering what the user typed, rather than performing the equivalent
278 of:
279 chdir("..");
281 In such a shell, the following commands would not necessarily produce
283 equivalent output for all directories:
284 cd .. && ls ls ..
286 This behavior is now the default. It is not consistent with the defini‐
288 tion of dot-dot in most historical practice; that is, while this behav‐
289 ior has been optionally available in the KornShell, other shells have
290 historically not supported this functionality. The logical pathname is
291 stored in the PWD environment variable when the cd utility completes
292 and this value is used to construct the next directory name if cd is
293 invoked with the −L option.
294
296 None.
297
299 Section 2.12, Shell Execution Environment, pwd
300 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
302 Variables, Section 12.2, Utility Syntax Guidelines
303 The System Interfaces volume of POSIX.1‐2008, chdir()
305
307 Portions of this text are reprinted and reproduced in electronic form
308 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
309 -- Portable Operating System Interface (POSIX), The Open Group Base
310 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
311 cal and Electronics Engineers, Inc and The Open Group. (This is
312 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
313 event of any discrepancy between this version and the original IEEE and
314 The Open Group Standard, the original IEEE and The Open Group Standard
315 is the referee document. The original Standard can be obtained online
316 at http://www.unix.org/online.html .
317 Any typographical or formatting errors that appear in this page are
319 most likely to have been introduced during the conversion of the source
320 files to man page format. To report such errors, see https://www.ker‐
321 nel.org/doc/man-pages/reporting_bugs.html .
322IEEE/The Open Group 2013 CD(1P)