Provided by: manpages-posix_2013a-2_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult the corresponding Linux  manual  page  for  details  of
       Linux behavior), or the interface may not be implemented on Linux.

NAME

       cd — change the working directory

SYNOPSIS

       cd [−L|−P] [directory]

       cd −

DESCRIPTION

       The  cd  utility  shall  change  the  working  directory  of  the  current shell execution
       environment (see Section 2.12, Shell Execution Environment)  by  executing  the  following
       steps  in sequence. (In the following steps, the symbol curpath represents an intermediate
       value used to simplify the  description  of  the  algorithm  used  by  cd.   There  is  no
       requirement that curpath be made visible to the application.)

        1. If  no  directory  operand  is  given  and  the  HOME environment variable is empty or
           undefined, the default behavior is implementation-defined and no further  steps  shall
           be taken.

        2. If  no  directory  operand is given and the HOME environment variable is set to a non-
           empty value, the cd utility shall behave  as  if  the  directory  named  in  the  HOME
           environment variable was specified as the directory operand.

        3. If  the  directory operand begins with a <slash> character, set curpath to the operand
           and proceed to step 7.

        4. If the first component of the directory operand is dot or dot-dot, proceed to step 6.

        5. Starting with the first pathname in the <colon>-separated pathnames of CDPATH (see the
           ENVIRONMENT  VARIABLES section) if the pathname is non-null, test if the concatenation
           of that pathname, a <slash> character if that pathname did  not  end  with  a  <slash>
           character,  and the directory operand names a directory. If the pathname is null, test
           if the concatenation of dot, a <slash> character, and the operand names  a  directory.
           In  either  case,  if the resulting string names an existing directory, set curpath to
           that string and proceed to step 7. Otherwise, repeat this step with the next  pathname
           in CDPATH until all pathnames have been tested.

        6. Set curpath to the directory operand.

        7. If  the  −P  option is in effect, proceed to step 10. If curpath does not begin with a
           <slash> character, set curpath to the string formed by the concatenation of the  value
           of  PWD, a <slash> character if the value of PWD did not end with a <slash> character,
           and curpath.

        8. The curpath value shall then be converted to canonical form  as  follows,  considering
           each component from beginning to end, in sequence:

            a. Dot  components  and  any  <slash>  characters  that  separate  them from the next
               component shall be deleted.

            b. For each dot-dot component, if there is a preceding component and  it  is  neither
               root nor dot-dot, then:

                i.  If  the  preceding  component  does  not  refer  (in  the context of pathname
                    resolution with symbolic links followed) to a directory, then the cd  utility
                    shall  display  an  appropriate  error  message and no further steps shall be
                    taken.

               ii.  The preceding component, all  <slash>  characters  separating  the  preceding
                    component  from  dot-dot, dot-dot, and all <slash> characters separating dot-
                    dot from the following component (if any) shall be deleted.

            c. An implementation may further simplify curpath by removing  any  trailing  <slash>
               characters  that  are not also leading <slash> characters, replacing multiple non-
               leading consecutive <slash> characters with a single <slash>, and replacing  three
               or more leading <slash> characters with a single <slash>.  If, as a result of this
               canonicalization, the curpath variable is null, no further steps shall be taken.

        9. If curpath is longer than {PATH_MAX} bytes (including the terminating  null)  and  the
           directory  operand  was  not  longer  than {PATH_MAX} bytes (including the terminating
           null), then curpath shall be converted from an  absolute  pathname  to  an  equivalent
           relative  pathname if possible. This conversion shall always be considered possible if
           the value of PWD, with a trailing <slash> added if it does not already have one, is an
           initial  substring  of  curpath.  Whether or not it is considered possible under other
           circumstances is unspecified.  Implementations  may  also  apply  this  conversion  if
           curpath  is  not longer than {PATH_MAX} bytes or the directory operand was longer than
           {PATH_MAX} bytes.

       10. The cd utility shall then perform actions equivalent to the  chdir()  function  called
           with  curpath  as  the  path  argument.  If  these actions fail for any reason, the cd
           utility shall display an appropriate error message and  the  remainder  of  this  step
           shall not be executed. If the −P option is not in effect, the PWD environment variable
           shall be set to the value that curpath had on entry to step 9 (i.e., before conversion
           to  a  relative pathname). If the −P option is in effect, the PWD environment variable
           shall be set to the string that would be output by pwd −P.  If there  is  insufficient
           permission  on the new directory, or on any parent of that directory, to determine the
           current working directory, the value of the PWD environment variable is unspecified.

       If, during the execution of the above steps, the PWD  environment  variable  is  set,  the
       OLDPWD  environment  variable  shall also be set to the value of the old working directory
       (that is the current working directory immediately prior to the call to cd).

OPTIONS

       The cd utility shall conform to the Base Definitions volume of POSIX.1‐2008, Section 12.2,
       Utility Syntax Guidelines.

       The following options shall be supported by the implementation:

       −L        Handle  the  operand  dot-dot  logically;  symbolic link components shall not be
                 resolved before dot-dot components are processed (see steps 8.  and  9.  in  the
                 DESCRIPTION).

       −P        Handle  the  operand  dot-dot  physically;  symbolic  link  components  shall be
                 resolved  before  dot-dot  components  are  processed  (see  step  7.   in   the
                 DESCRIPTION).

       If  both  −L and −P options are specified, the last of these options shall be used and all
       others ignored. If neither −L nor −P is specified, the operand shall  be  handled  dot-dot
       logically; see the DESCRIPTION.

OPERANDS

       The following operands shall be supported:

       directory An  absolute  or  relative  pathname  of the directory that shall become the new
                 working directory. The interpretation of a relative pathname by  cd  depends  on
                 the  −L  option and the CDPATH and PWD environment variables. If directory is an
                 empty string, the results are unspecified.

       −         When a <hyphen> is used as the operand, this shall be equivalent to the command:

                     cd "$OLDPWD" && pwd

                 which changes to the previous working directory and then writes its name.

STDIN

       Not used.

INPUT FILES

       None.

ENVIRONMENT VARIABLES

       The following environment variables shall affect the execution of cd:

       CDPATH    A <colon>-separated list of pathnames that refer to directories. The cd  utility
                 shall  use this list in its attempt to change the directory, as described in the
                 DESCRIPTION. An empty string in place of a  directory  pathname  represents  the
                 current  directory.  If  CDPATH is not set, it shall be treated as if it were an
                 empty string.

       HOME      The name of the directory, used when no directory operand is specified.

       LANG      Provide a default value for the internationalization variables that are unset or
                 null.   (See   the   Base  Definitions  volume  of  POSIX.1‐2008,  Section  8.2,
                 Internationalization  Variables  for  the  precedence  of   internationalization
                 variables used to determine the values of locale categories.)

       LC_ALL    If  set  to  a  non-empty  string  value,  override  the values of all the other
                 internationalization variables.

       LC_CTYPE  Determine the locale for the interpretation of sequences of bytes of  text  data
                 as  characters  (for example, single-byte as opposed to multi-byte characters in
                 arguments).

       LC_MESSAGES
                 Determine the locale that should be used to affect the format  and  contents  of
                 diagnostic messages written to standard error.

       NLSPATH   Determine the location of message catalogs for the processing of LC_MESSAGES.

       OLDPWD    A pathname of the previous working directory, used by cd .

       PWD       This  variable  shall  be set as specified in the DESCRIPTION. If an application
                 sets or unsets the value of PWD, the behavior of cd is unspecified.

ASYNCHRONOUS EVENTS

       Default.

STDOUT

       If a non-empty directory name from CDPATH is used,  or  if  cd    is  used,  an  absolute
       pathname of the new working directory shall be written to the standard output as follows:

           "%s\n", <new directory>

       Otherwise, there shall be no output.

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       None.

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       The following exit values shall be returned:

        0    The directory was successfully changed.

       >0    An error occurred.

CONSEQUENCES OF ERRORS

       The working directory shall remain unchanged.

       The following sections are informative.

APPLICATION USAGE

       Since cd affects the current shell execution environment, it is always provided as a shell
       regular built-in. If it is called in a subshell or separate utility execution environment,
       such as one of the following:

           (cd /tmp)
           nohup cd
           find . −exec cd {} \;

       it does not affect the working directory of the caller's environment.

       The user must have execute (search) permission in directory in order to change to it.

EXAMPLES

       The  following  template  can  be used to perform processing in the directory specified by
       location and end up in the current working directory in use before the  first  cd  command
       was issued:

           cd location
           if [ $? -ne 0 ]
           then
               print error message
               exit 1
           fi
           ... do whatever is desired as long as the OLDPWD environment variable
               is not modified
           cd -

RATIONALE

       The  use  of  the CDPATH was introduced in the System V shell. Its use is analogous to the
       use of the PATH variable in the shell. The BSD C shell used a shell parameter  cdpath  for
       this purpose.

       A  common  extension  when  HOME  is undefined is to get the login directory from the user
       database for the invoking user. This does not occur on System V implementations.

       Some historical shells, such as the KornShell, took special  actions  when  the  directory
       name  contained a dot-dot component, selecting the logical parent of the directory, rather
       than the actual parent directory; that is, it moved up one level toward  the  '/'  in  the
       pathname, remembering what the user typed, rather than performing the equivalent of:

           chdir("..");

       In  such  a  shell, the following commands would not necessarily produce equivalent output
       for all directories:

           cd .. && ls      ls ..

       This behavior is now the default. It is not consistent with the definition of  dot-dot  in
       most  historical  practice;  that is, while this behavior has been optionally available in
       the KornShell, other shells  have  historically  not  supported  this  functionality.  The
       logical  pathname  is stored in the PWD environment variable when the cd utility completes
       and this value is used to construct the next directory name if cd is invoked with  the  −L
       option.

FUTURE DIRECTIONS

       None.

SEE ALSO

       Section 2.12, Shell Execution Environment, pwd

       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment Variables, Section
       12.2, Utility Syntax Guidelines

       The System Interfaces volume of POSIX.1‐2008, chdir()

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2013  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013  by  the
       Institute  of  Electrical  and  Electronics  Engineers,  Inc and The Open Group.  (This is
       POSIX.1-2008 with the  2013  Technical  Corrigendum  1  applied.)  In  the  event  of  any
       discrepancy  between  this  version and the original IEEE and The Open Group Standard, the
       original IEEE and The Open Group Standard is the referee document. The  original  Standard
       can be obtained online at http://www.unix.org/online.html .

       Any  typographical  or  formatting errors that appear in this page are most likely to have
       been introduced during the conversion of the source files to man page  format.  To  report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .