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
21 The cd utility shall change the working directory of the current shell
22 execution environment (see Shell Execution Environment ) by executing
23 the following steps in sequence. (In the following steps, the symbol
24 curpath represents an intermediate value used to simplify the descrip‐
25 tion of the algorithm used by cd. There is no requirement that curpath
26 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 curpath
38 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, and the directory operand names a directory. If the
47 pathname is null, test if the concatenation of dot, a slash charac‐
48 ter, and the operand names a directory. In either case, if the
49 resulting string names an existing directory, set curpath to that
50 string and proceed to step 7. Otherwise, repeat this step with the
51 next pathname in CDPATH until all pathnames have been tested.
52 6. Set curpath to the string formed by the concatenation of the value
54 of PWD, a slash character, and the operand.
55 7. If the -P option is in effect, the cd utility shall perform actions
57 equivalent to the chdir() function, called with curpath as the path
58 argument. If these actions succeed, the PWD environment variable
59 shall be set to an absolute pathname for the current working direc‐
60 tory and shall not contain filename components that, in the context
61 of pathname resolution, refer to a file of type symbolic link. If
62 there is insufficient permission on the new directory, or on any
63 parent of that directory, to determine the current working direc‐
64 tory, the value of the PWD environment variable is unspecified. If
65 the actions equivalent to chdir() fail for any reason, the cd util‐
66 ity shall display an appropriate error message and not alter the
67 PWD environment variable. Whether the actions equivalent to chdir()
68 succeed or fail, no further steps shall be taken.
69 8. The curpath value shall then be converted to canonical form as fol‐
71 lows, considering each component from beginning to end, in
72 sequence:
73 a. Dot components and any slashes that separate them from the next
75 component shall be deleted.
76 b. For each dot-dot component, if there is a preceding component
78 and it is neither root nor dot-dot, the preceding component,
79 all slashes separating the preceding component from dot-dot,
80 dot-dot and all slashes separating dot-dot from the following
81 component shall be deleted.
82 c. An implementation may further simplify curpath by removing any
84 trailing slash characters that are not also leading slashes,
85 replacing multiple non-leading consecutive slashes with a sin‐
86 gle slash, and replacing three or more leading slashes with a
87 single slash. If, as a result of this canonicalization, the
88 curpath variable is null, no further steps shall be taken.
89 9. The cd utility shall then perform actions equivalent to the chdir()
91 function called with curpath as the path argument. If these actions
92 failed for any reason, the cd utility shall display an appropriate
93 error message and no further steps shall be taken. The PWD envi‐
94 ronment variable shall be set to curpath.
95 If, during the execution of the above steps, the PWD environment vari‐
97 able is changed, the OLDPWD environment variable shall also be changed
98 to the value of the old working directory (that is the current working
99 directory immediately prior to the call to cd).
100
102 The cd utility shall conform to the Base Definitions volume of
103 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
104 The following options shall be supported by the implementation:
106 -L Handle the operand dot-dot logically; symbolic link components
108 shall not be resolved before dot-dot components are processed
109 (see steps 8. and 9. in the DESCRIPTION).
110 -P Handle the operand dot-dot physically; symbolic link components
112 shall be resolved before dot-dot components are processed (see
113 step 7. in the DESCRIPTION).
114 If both -L and -P options are specified, the last of these options
117 shall be used and all others ignored. If neither -L nor -P is speci‐
118 fied, the operand shall be handled dot-dot logically; see the DESCRIP‐
119 TION.
120
122 The following operands shall be supported:
123 directory
125 An absolute or relative pathname of the directory that shall
126 become the new working directory. The interpretation of a rela‐
127 tive pathname by cd depends on the -L option and the CDPATH and
128 PWD environment variables. If directory is an empty string, the
129 results are unspecified.
130 - When a hyphen is used as the operand, this shall be equivalent
132 to the command:
133 cd "$OLDPWD" && pwd
136 which changes to the previous working directory and then writes its
138 name.
139
142 Not used.
143
145 None.
146
148 The following environment variables shall affect the execution of cd:
149 CDPATH A colon-separated list of pathnames that refer to directories.
151 The cd utility shall use this list in its attempt to change the
152 directory, as described in the DESCRIPTION. An empty string in
153 place of a directory pathname represents the current directory.
154 If CDPATH is not set, it shall be treated as if it were an empty
155 string.
156 HOME The name of the directory, used when no directory operand is
158 specified.
159 LANG Provide a default value for the internationalization variables
161 that are unset or null. (See the Base Definitions volume of
162 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
163 ables for the precedence of internationalization variables used
164 to determine the values of locale categories.)
165 LC_ALL If set to a non-empty string value, override the values of all
167 the other internationalization variables.
168 LC_CTYPE
170 Determine the locale for the interpretation of sequences of
171 bytes of text data as characters (for example, single-byte as
172 opposed to multi-byte characters in arguments).
173 LC_MESSAGES
175 Determine the locale that should be used to affect the format
176 and contents of diagnostic messages written to standard error.
177 NLSPATH
179 Determine the location of message catalogs for the processing of
180 LC_MESSAGES .
181 OLDPWD A pathname of the previous working directory, used by cd -.
183 PWD This variable shall be set as specified in the DESCRIPTION. If
185 an application sets or unsets the value of PWD, the behavior of
186 cd is unspecified.
187
190 Default.
191
193 If a non-empty directory name from CDPATH is used, or if cd - is used,
194 an absolute pathname of the new working directory shall be written to
195 the standard output as follows:
196 "%s\n", <new directory>
199 Otherwise, there shall be no output.
201
203 The standard error shall be used only for diagnostic messages.
204
206 None.
207
209 None.
210
212 The following exit values shall be returned:
213 0 The directory was successfully changed.
215 >0 An error occurred.
217
220 The working directory shall remain unchanged.
221 The following sections are informative.
223
225 Since cd affects the current shell execution environment, it is always
226 provided as a shell regular built-in. If it is called in a subshell or
227 separate utility execution environment, such as one of the following:
228 (cd /tmp)
231 nohup cd
232 find . -exec cd {} \;
233 it does not affect the working directory of the caller's environment.
235 The user must have execute (search) permission in directory in order to
237 change to it.
238
240 None.
241
243 The use of the CDPATH was introduced in the System V shell. Its use is
244 analogous to the use of the PATH variable in the shell. The BSD C shell
245 used a shell parameter cdpath for this purpose.
246 A common extension when HOME is undefined is to get the login directory
248 from the user database for the invoking user. This does not occur on
249 System V implementations.
250 Some historical shells, such as the KornShell, took special actions
252 when the directory name contained a dot-dot component, selecting the
253 logical parent of the directory, rather than the actual parent direc‐
254 tory; that is, it moved up one level toward the '/' in the pathname,
255 remembering what the user typed, rather than performing the equivalent
256 of:
257 chdir("..");
260 In such a shell, the following commands would not necessarily produce
262 equivalent output for all directories:
263 cd .. && ls ls ..
266 This behavior is now the default. It is not consistent with the defini‐
268 tion of dot-dot in most historical practice; that is, while this behav‐
269 ior has been optionally available in the KornShell, other shells have
270 historically not supported this functionality. The logical pathname is
271 stored in the PWD environment variable when the cd utility completes
272 and this value is used to construct the next directory name if cd is
273 invoked with the -L option.
274
276 None.
277
279 Shell Execution Environment, pwd, the System Interfaces volume of
280 IEEE Std 1003.1-2001, chdir()
281
283 Portions of this text are reprinted and reproduced in electronic form
284 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
285 -- Portable Operating System Interface (POSIX), The Open Group Base
286 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
287 Electrical and Electronics Engineers, Inc and The Open Group. In the
288 event of any discrepancy between this version and the original IEEE and
289 The Open Group Standard, the original IEEE and The Open Group Standard
290 is the referee document. The original Standard can be obtained online
291 at http://www.opengroup.org/unix/online.html .
292IEEE/The Open Group 2003 CD(1P)