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

DESCRIPTION

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
27        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
31        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
36        3. If the directory operand begins with a <slash> character, set  cur‐
37           path to the operand and proceed to step 7.
38
39        4. If  the first component of the directory operand is dot or dot-dot,
40           proceed to step 6.
41
42        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
53        6. Set curpath to the directory operand.
54
55        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
61        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
65            a. Dot  components  and  any <slash> characters that separate them
66               from the next component shall be deleted.
67
68            b. For each dot-dot component, if there is a  preceding  component
69               and it is neither root nor dot-dot, then:
70
71                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
76               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
81            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
89        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
101       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
114       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

OPTIONS

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

OPERANDS

139       The following operands shall be supported:
140
141       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
147       -         When  a  <hyphen-minus> is used as the operand, this shall be
148                 equivalent to the command:
149
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‐2017, 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
211           "%s\n", <new directory>
212
213       Otherwise, there shall be no output.
214

STDERR

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

OUTPUT FILES

219       None.
220

EXTENDED DESCRIPTION

222       None.
223

EXIT STATUS

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

CONSEQUENCES OF ERRORS

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

APPLICATION USAGE

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

EXAMPLES

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
256
257           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

RATIONALE

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
272       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
276       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
283
284           chdir("..");
285
286       In  such  a shell, the following commands would not necessarily produce
287       equivalent output for all directories:
288
289
290           cd .. && ls      ls ..
291
292       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

FUTURE DIRECTIONS

301       None.
302

SEE ALSO

304       Section 2.12, Shell Execution Environment, pwd
305
306       The Base Definitions volume of  POSIX.1‐2017,  Chapter  8,  Environment
307       Variables, Section 12.2, Utility Syntax Guidelines
308
309       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
322       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 .
326
327
328
329IEEE/The Open Group                  2017                               CD(1P)
Impressum