man-pages/man1p/cd.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "CD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" cd 
.SH NAME
cd \- change the working directory
.SH SYNOPSIS
.LP
\fBcd\fP \fB[\fP\fB-L | -P\fP\fB] [\fP\fIdirectory\fP\fB]\fP\fB
.br
.sp
cd -
.br
\fP
.SH DESCRIPTION
.LP
The \fIcd\fP utility shall change the working directory of the current
shell execution environment (see \fIShell Execution Environment\fP
) by executing the following steps in sequence. (In the
following steps, the symbol \fBcurpath\fP represents an intermediate
value used to simplify the description of the algorithm used
by \fIcd\fP. There is no requirement that \fBcurpath\fP be made visible
to the application.)
.IP " 1." 4
If no \fIdirectory\fP operand is given and the \fIHOME\fP environment
variable is empty or undefined, the default behavior is
implementation-defined and no further steps shall be taken.
.LP
.IP " 2." 4
If no \fIdirectory\fP operand is given and the \fIHOME\fP environment
variable is set to a non-empty value, the \fIcd\fP
utility shall behave as if the directory named in the \fIHOME\fP environment
variable was specified as the \fIdirectory\fP
operand.
.LP
.IP " 3." 4
If the \fIdirectory\fP operand begins with a slash character, set
\fBcurpath\fP to the operand and proceed to step 7.
.LP
.IP " 4." 4
If the first component of the \fIdirectory\fP operand is dot or dot-dot,
proceed to step 6.
.LP
.IP " 5." 4
Starting with the first pathname in the colon-separated pathnames
of \fICDPATH\fP (see the ENVIRONMENT VARIABLES section) if
the pathname is non-null, test if the concatenation of that pathname,
a slash character, and the \fIdirectory\fP 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 \fBcurpath\fP to that string and proceed to step 7.
Otherwise, repeat this step with the next pathname in \fICDPATH\fP
until all pathnames have been tested.
.LP
.IP " 6." 4
Set \fBcurpath\fP to the string formed by the concatenation of the
value of \fIPWD ,\fP a slash character, and the
operand.
.LP
.IP " 7." 4
If the \fB-P\fP option is in effect, the \fIcd\fP utility shall perform
actions equivalent to the \fIchdir\fP() function, called with \fBcurpath\fP
as the \fIpath\fP argument. If these actions
succeed, the \fIPWD\fP 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
insufficient permission on the new directory, or on any parent of
that directory, to determine the current working directory, the
value of the \fIPWD\fP environment variable is unspecified. If the
actions equivalent to \fIchdir\fP() fail for any reason, the \fIcd\fP
utility shall display an appropriate error message
and not alter the \fIPWD\fP environment variable. Whether the actions
equivalent to \fIchdir\fP() succeed or fail, no further steps shall
be taken.
.LP
.IP " 8." 4
The \fBcurpath\fP value shall then be converted to canonical form
as follows, considering each component from beginning to end,
in sequence:
.RS
.IP " a." 4
Dot components and any slashes that separate them from the next component
shall be deleted.
.LP
.IP " b." 4
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.
.LP
.IP " c." 4
An implementation may further simplify \fBcurpath\fP 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 \fBcurpath\fP
variable is null, no further steps shall be taken.
.LP
.RE
.LP
.IP " 9." 4
The \fIcd\fP utility shall then perform actions equivalent to the
\fIchdir\fP() function
called with \fBcurpath\fP as the \fIpath\fP argument. If these actions
failed for any reason, the \fIcd\fP utility shall display
an appropriate error message and no further steps shall be taken.
The \fIPWD\fP environment variable shall be set to
\fBcurpath\fP.
.LP
.LP
If, during the execution of the above steps, the \fIPWD\fP environment
variable is changed, the \fIOLDPWD\fP 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 \fIcd\fP).
.SH OPTIONS
.LP
The \fIcd\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported by the implementation:
.TP 7
\fB-L\fP
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).
.TP 7
\fB-P\fP
Handle the operand dot-dot physically; symbolic link components shall
be resolved before dot-dot components are processed (see
step 7. in the DESCRIPTION).
.sp
.LP
If both \fB-L\fP and \fB-P\fP options are specified, the last of these
options shall be used and all others ignored. If
neither \fB-L\fP nor \fB-P\fP is specified, the operand shall be handled
dot-dot logically; see the DESCRIPTION.
.SH OPERANDS
.LP
The following operands shall be supported:
.TP 7
\fIdirectory\fP
An absolute or relative pathname of the directory that shall become
the new working directory. The interpretation of a relative
pathname by \fIcd\fP depends on the \fB-L\fP option and the \fICDPATH\fP
and \fIPWD\fP environment variables. If
\fIdirectory\fP is an empty string, the results are unspecified.
.TP 7
-
When a hyphen is used as the operand, this shall be equivalent to
the command: 
.sp
.RS
.nf

\fBcd "$OLDPWD" && pwd
\fP
.fi
.RE
.LP
which changes to the previous working directory and then writes its
name.
.sp
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
None.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIcd\fP:
.TP 7
\fICDPATH\fP
A colon-separated list of pathnames that refer to directories. The
\fIcd\fP 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 \fICDPATH\fP is not set, it shall be treated as if it
were an empty string.
.TP 7
\fIHOME\fP
The name of the directory, used when no \fIdirectory\fP operand is
specified.
.TP 7
\fILANG\fP
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 precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.TP 7
\fIOLDPWD\fP
A pathname of the previous working directory, used by \fIcd\fP \fB-\fP.
.TP 7
\fIPWD\fP
This variable shall be set as specified in the DESCRIPTION. If an
application sets or unsets the value of \fIPWD ,\fP the
behavior of \fIcd\fP is unspecified.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
If a non-empty directory name from \fICDPATH\fP is used, or if \fIcd\fP
\fB-\fP is used, an absolute pathname of the new
working directory shall be written to the standard output as follows:
.sp
.RS
.nf

\fB"%s\\n", <\fP\fInew directory\fP\fB>
\fP
.fi
.RE
.LP
Otherwise, there shall be no output.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
The directory was successfully changed.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
The working directory shall remain unchanged.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
Since \fIcd\fP 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:
.sp
.RS
.nf

\fB(cd /tmp)
nohup cd
find . -exec cd {} \\;
\fP
.fi
.RE
.LP
it does not affect the working directory of the caller's environment.
.LP
The user must have execute (search) permission in \fIdirectory\fP
in order to change to it.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
The use of the \fICDPATH\fP was introduced in the System V shell.
Its use is analogous to the use of the \fIPATH\fP variable
in the shell. The BSD C shell used a shell parameter \fIcdpath\fP
for this purpose.
.LP
A common extension when \fIHOME\fP is undefined is to get the login
directory from the user database for the invoking user.
This does not occur on System V implementations.
.LP
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
\fB'/'\fP in the pathname, remembering what the user typed, rather
than performing the equivalent of:
.sp
.RS
.nf

\fBchdir("..");
\fP
.fi
.RE
.LP
In such a shell, the following commands would not necessarily produce
equivalent output for all directories:
.sp
.RS
.nf

\fBcd .. && ls      ls ..
\fP
.fi
.RE
.LP
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 \fIPWD\fP environment
variable when the \fIcd\fP utility completes and this
value is used to construct the next directory name if \fIcd\fP is
invoked with the \fB-L\fP option.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIShell Execution Environment\fP , \fIpwd\fP , the System
Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIchdir\fP()
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications 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 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 .