mirror of https://github.com/mkerrisk/man-pages
351 lines
11 KiB
Groff
351 lines
11 KiB
Groff
.\" 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 .
|