1CD(1P)                     POSIX Programmer's Manual                    CD(1P)
2
3
4

PROLOG

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

NAME

12       cd - change the working directory
13

SYNOPSIS

15       cd [-L | -P] [directory]
16
17       cd -
18
19

DESCRIPTION

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
28        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
32        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
37        3. If the directory operand begins with a slash character, set curpath
38           to the operand and proceed to step 7.
39
40        4. If  the first component of the directory operand is dot or dot-dot,
41           proceed to step 6.
42
43        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
53        6. Set curpath to the string formed by the concatenation of the  value
54           of PWD,  a slash character, and the operand.
55
56        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
70        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
74            a. Dot components and any slashes that separate them from the next
75               component shall be deleted.
76
77            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
83            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
90        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
96       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

OPTIONS

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
105       The following options shall be supported by the implementation:
106
107       -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
111       -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
115
116       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

OPERANDS

122       The following operands shall be supported:
123
124       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
131       -      When a hyphen is used as the operand, this shall  be  equivalent
132              to the command:
133
134
135              cd "$OLDPWD" && pwd
136
137       which  changes  to  the  previous working directory and then writes its
138       name.
139
140

STDIN

142       Not used.
143

INPUT FILES

145       None.
146

ENVIRONMENT VARIABLES

148       The following environment variables shall affect the execution of cd:
149
150       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
157       HOME   The  name  of  the  directory, used when no directory operand is
158              specified.
159
160       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
166       LC_ALL If set to a non-empty string value, override the values  of  all
167              the other internationalization variables.
168
169       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
174       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
178       NLSPATH
179              Determine the location of message catalogs for the processing of
180              LC_MESSAGES .
181
182       OLDPWD A pathname of the previous working directory, used by cd -.
183
184       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
188

ASYNCHRONOUS EVENTS

190       Default.
191

STDOUT

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
197
198              "%s\n", <new directory>
199
200       Otherwise, there shall be no output.
201

STDERR

203       The standard error shall be used only for diagnostic messages.
204

OUTPUT FILES

206       None.
207

EXTENDED DESCRIPTION

209       None.
210

EXIT STATUS

212       The following exit values shall be returned:
213
214        0     The directory was successfully changed.
215
216       >0     An error occurred.
217
218

CONSEQUENCES OF ERRORS

220       The working directory shall remain unchanged.
221
222       The following sections are informative.
223

APPLICATION USAGE

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
229
230              (cd /tmp)
231              nohup cd
232              find . -exec cd {} \;
233
234       it does not affect the working directory of the caller's environment.
235
236       The user must have execute (search) permission in directory in order to
237       change to it.
238

EXAMPLES

240       None.
241

RATIONALE

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
247       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
251       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
258
259              chdir("..");
260
261       In  such  a shell, the following commands would not necessarily produce
262       equivalent output for all directories:
263
264
265              cd .. && ls      ls ..
266
267       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

FUTURE DIRECTIONS

276       None.
277

SEE ALSO

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 .
292
293
294
295IEEE/The Open Group                  2003                               CD(1P)
Impressum