Man Pages

cd(1p) - phpMan cd(1p) - phpMan

Command: man perldoc info search(apropos)  


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



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (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 Shell Execu-
       tion 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 direc-
           tory 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,  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 string formed by the concatenation of the value of PWD,   a  slash  character,  and  the
           operand.


        7. If  the  -P  option  is in effect, the cd utility shall perform actions equivalent to the chdir() function,
           called with curpath as the path argument. If these actions succeed, the PWD environment variable  shall  be
           set  to  an  absolute  pathname for the current working directory and shall not contain filename components
           that, in the context of pathname resolution, refer to a file of type symbolic link. If  there  is  insuffi-
           cient 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 the actions equivalent  to  chdir()
           fail  for any reason, the cd utility shall display an appropriate error message and not alter the PWD envi-
           ronment variable. Whether the actions equivalent to chdir() succeed or fail,  no  further  steps  shall  be
           taken.


        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 slashes 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,  the
               preceding  component,  all  slashes  separating  the  preceding component from dot-dot, dot-dot and all
               slashes separating dot-dot from the following component shall be deleted.


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



        9. The  cd  utility  shall  then perform actions equivalent to the chdir() function called with curpath as the
           path argument. If these actions failed for any reason, the cd utility shall display  an  appropriate  error
           message and no further steps shall be taken.  The PWD environment variable shall be set to curpath.


       If,  during  the  execution of the above steps, the PWD environment variable is changed, the OLDPWD environment
       variable shall also be changed 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 IEEE Std 1003.1-2001, Section 12.2, Utility Syn-
       tax 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 com-
              ponents 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 compo-
              nents 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  direc-
              tory  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 IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables for the prece-
              dence 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 exam-
              ple, 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  writ-
              ten 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
       None.

RATIONALE
       The use of the CDPATH was introduced in the System V shell.  Its use is analogous to the use of the PATH  vari-
       able 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 prac-
       tice; that is, while this behavior has been optionally available in the KornShell, other shells  have  histori-
       cally 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
       Shell Execution Environment, pwd, the System Interfaces volume of IEEE Std 1003.1-2001, chdir()

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  Issue  6,  Copyright (C) 2001-2003 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 Stan-
       dard,  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 .



IEEE/The Open Group                  2003                               CD(1P)