CD(1)                      POSIX Programmer's Manual                     CD(1)



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

NNAAMMEE
       cd -- change the working directory

SSYYNNOOPPSSIISS
       cd [[-L|-P]] [[_d_i_r_e_c_t_o_r_y]]

       cd -

DDEESSCCRRIIPPTTIIOONN
       The _c_d utility shall change the working directory of the current shell
       execution environment (see _S_e_c_t_i_o_n _2_._1_2, _S_h_e_l_l _E_x_e_c_u_t_i_o_n _E_n_v_i_r_o_n_m_e_n_t)
       by executing the following steps in sequence. (In the following steps,
       the symbol ccuurrppaatthh represents an intermediate value used to simplify
       the description of the algorithm used by _c_d.  There is no requirement
       that ccuurrppaatthh be made visible to the application.)

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

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

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

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

        5. Starting with the first pathname in the <colon>-separated pathnames
           of _C_D_P_A_T_H (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 _d_i_r_e_c_t_o_r_y 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 ccuurrppaatthh to that string and
           proceed to step 7. Otherwise, repeat this step with the next
           pathname in _C_D_P_A_T_H until all pathnames have been tested.

        6. Set ccuurrppaatthh to the _d_i_r_e_c_t_o_r_y operand.

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

        8. The ccuurrppaatthh 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 _c_d 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 ccuurrppaatthh 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 ccuurrppaatthh variable is null,
               no further steps shall be taken.

        9. If ccuurrppaatthh is longer than {PATH_MAX} bytes (including the
           terminating null) and the _d_i_r_e_c_t_o_r_y operand was not longer than
           {PATH_MAX} bytes (including the terminating null), then ccuurrppaatthh
           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 _P_W_D, with a trailing <slash>
           added if it does not already have one, is an initial substring of
           ccuurrppaatthh.  Whether or not it is considered possible under other
           circumstances is unspecified. Implementations may also apply this
           conversion if ccuurrppaatthh is not longer than {PATH_MAX} bytes or the
           _d_i_r_e_c_t_o_r_y operand was longer than {PATH_MAX} bytes.

       10. The _c_d utility shall then perform actions equivalent to the _c_h_d_i_r()
           function called with ccuurrppaatthh as the _p_a_t_h argument. If these actions
           fail for any reason, the _c_d utility shall display an appropriate
           error message and the remainder of this step shall not be executed.
           If the --PP option is not in effect, the _P_W_D environment variable
           shall be set to the value that ccuurrppaatthh had on entry to step 9
           (i.e., before conversion to a relative pathname). If the --PP option
           is in effect, the _P_W_D environment variable shall be set to the
           string that would be output by _p_w_d --PP.  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 _P_W_D environment variable is unspecified.

       If, during the execution of the above steps, the _P_W_D environment
       variable is set, the _O_L_D_P_W_D 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 _c_d).

OOPPTTIIOONNSS
       The _c_d utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported by the implementation:

       --LL        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).

       --PP        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 --LL and --PP options are specified, the last of these options
       shall be used and all others ignored. If neither --LL nor --PP is
       specified, the operand shall be handled dot-dot logically; see the
       DESCRIPTION.

OOPPEERRAANNDDSS
       The following operands shall be supported:

       _d_i_r_e_c_t_o_r_y An absolute or relative pathname of the directory that shall
                 become the new working directory. The interpretation of a
                 relative pathname by _c_d depends on the --LL option and the
                 _C_D_P_A_T_H and _P_W_D environment variables. If _d_i_r_e_c_t_o_r_y is an
                 empty string, the results are unspecified.

       -         When a <hyphen-minus> 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.

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _c_d:

       _C_D_P_A_T_H    A <colon>-separated list of pathnames that refer to
                 directories. The _c_d 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 _C_D_P_A_T_H is not set, it
                 shall be treated as if it were an empty string.

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

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

       _L_C___C_T_Y_P_E  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).

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

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

       _O_L_D_P_W_D    A pathname of the previous working directory, used by _c_d --.

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

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

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


           "%s\n", <_n_e_w _d_i_r_e_c_t_o_r_y>

       Otherwise, there shall be no output.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    The directory was successfully changed.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       The working directory shall remain unchanged.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Since _c_d 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 _d_i_r_e_c_t_o_r_y in order to
       change to it.

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


           cd _l_o_c_a_t_i_o_n
           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 -

RRAATTIIOONNAALLEE
       The use of the _C_D_P_A_T_H was introduced in the System V shell. Its use is
       analogous to the use of the _P_A_T_H variable in the shell. The BSD C shell
       used a shell parameter _c_d_p_a_t_h for this purpose.

       A common extension when _H_O_M_E 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 _P_W_D environment variable when the _c_d utility
       completes and this value is used to construct the next directory name
       if _c_d is invoked with the --LL option.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._1_2, _S_h_e_l_l _E_x_e_c_u_t_i_o_n _E_n_v_i_r_o_n_m_e_n_t, _p_w_d

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

       The System Interfaces volume of POSIX.1-2017, _c_h_d_i_r()

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  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.opengroup.org/unix/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 .



IEEE/The Open Group                  2017                                CD(1)
