cd

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



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 .



IEEE/The Open Group                   2013                            CD(1POSIX)