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
11

NAME

13       cd — change the working directory
14

SYNOPSIS

16       cd [−L|−P] [directory]
17
18       cd −
19

DESCRIPTION

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
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  cur‐
38           path 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  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
54        6. Set curpath to the directory operand.
55
56        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
62        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
66            a. Dot  components  and  any <slash> characters that separate them
67               from the next component shall be deleted.
68
69            b. For each dot-dot component, if there is a  preceding  component
70               and it is neither root nor dot-dot, then:
71
72                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
77               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
82            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
90        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
102       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
115       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

OPTIONS

121       The  cd  utility  shall  conform  to  the  Base  Definitions  volume of
122       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
123
124       The following options shall be supported by the implementation:
125
126       −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
130       −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
134       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

OPERANDS

140       The following operands shall be supported:
141
142       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
148       −         When a <hyphen> is used as the operand, this shall be equiva‐
149                 lent to the command:
150
151                     cd "$OLDPWD" && pwd
152
153                 which changes to the  previous  working  directory  and  then
154                 writes its name.
155

STDIN

157       Not used.
158

INPUT FILES

160       None.
161

ENVIRONMENT VARIABLES

163       The following environment variables shall affect the execution of cd:
164
165       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
172       HOME      The name of the directory, used when no directory operand  is
173                 specified.
174
175       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
181       LC_ALL    If  set  to  a non-empty string value, override the values of
182                 all the other internationalization variables.
183
184       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
188       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
193       NLSPATH   Determine the location of message catalogs for the processing
194                 of LC_MESSAGES.
195
196       OLDPWD    A pathname of the previous working directory, used by cd .
197
198       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

ASYNCHRONOUS EVENTS

203       Default.
204

STDOUT

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
210           "%s\n", <new directory>
211
212       Otherwise, there shall be no output.
213

STDERR

215       The standard error shall be used only for diagnostic messages.
216

OUTPUT FILES

218       None.
219

EXTENDED DESCRIPTION

221       None.
222

EXIT STATUS

224       The following exit values shall be returned:
225
226        0    The directory was successfully changed.
227
228       >0    An error occurred.
229

CONSEQUENCES OF ERRORS

231       The working directory shall remain unchanged.
232
233       The following sections are informative.
234

APPLICATION USAGE

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
240           (cd /tmp)
241           nohup cd
242           find . −exec cd {} \;
243
244       it does not affect the working directory of the caller's environment.
245
246       The user must have execute (search) permission in directory in order to
247       change to it.
248

EXAMPLES

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
254           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

RATIONALE

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
269       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
273       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
280           chdir("..");
281
282       In  such  a shell, the following commands would not necessarily produce
283       equivalent output for all directories:
284
285           cd .. && ls      ls ..
286
287       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

FUTURE DIRECTIONS

296       None.
297

SEE ALSO

299       Section 2.12, Shell Execution Environment, pwd
300
301       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
302       Variables, Section 12.2, Utility Syntax Guidelines
303
304       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
318       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 .
322
323
324
325IEEE/The Open Group                  2013                               CD(1P)
Impressum