407 lines
15 KiB
HTML
407 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>cd</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="cd"></a> <a name="tag_04_15"></a><!-- cd -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_15_01"></a>NAME</h4>
|
|
|
|
<blockquote>cd - change the working directory</blockquote>
|
|
|
|
<h4><a name="tag_04_15_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>cd</tt> <b>[</b><tt>-L</tt><b>] [</b><tt>-P</tt><b>] [</b><i>directory</i><b>]</b><tt><br>
|
|
<br>
|
|
cd -<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>cd</i> utility shall change the working directory of the current shell execution environment (see <a href=
|
|
"xcu_chap02.html#tag_02_12"><i>Shell Execution Environment</i></a> ) by executing the following steps in sequence. (In the
|
|
following steps, the symbol <b>curpath</b> represents an intermediate value used to simplify the description of the algorithm used
|
|
by <i>cd</i>. There is no requirement that <b>curpath</b> be made visible to the application.)</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>If no <i>directory</i> operand is given and the <i>HOME</i> environment variable is empty or undefined, the default behavior is
|
|
implementation-defined and no further steps shall be taken.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If no <i>directory</i> operand is given and the <i>HOME</i> environment variable is set to a non-empty value, the <i>cd</i>
|
|
utility shall behave as if the directory named in the <i>HOME</i> environment variable was specified as the <i>directory</i>
|
|
operand.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the <i>directory</i> operand begins with a slash character, set <b>curpath</b> to the operand and proceed to step 7.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the first component of the <i>directory</i> operand is dot or dot-dot, proceed to step 6.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Starting with the first pathname in the colon-separated pathnames of <i>CDPATH</i> (see the ENVIRONMENT VARIABLES section) if
|
|
the pathname is non-null, test if the concatenation of that pathname, a slash character, and the <i>directory</i> 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 <b>curpath</b> to that string and proceed to step 7.
|
|
Otherwise, repeat this step with the next pathname in <i>CDPATH</i> until all pathnames have been tested.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Set <b>curpath</b> to the string formed by the concatenation of the value of <i>PWD ,</i> a slash character, and the
|
|
operand.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the <b>-P</b> option is in effect, the <i>cd</i> utility shall perform actions equivalent to the <a href=
|
|
"../functions/chdir.html"><i>chdir</i>()</a> function, called with <b>curpath</b> as the <i>path</i> argument. If these actions
|
|
succeed, the <i>PWD</i> 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 <i>PWD</i> environment variable is unspecified. If the actions equivalent to <a href=
|
|
"../functions/chdir.html"><i>chdir</i>()</a> fail for any reason, the <i>cd</i> utility shall display an appropriate error message
|
|
and not alter the <i>PWD</i> environment variable. Whether the actions equivalent to <a href=
|
|
"../functions/chdir.html"><i>chdir</i>()</a> succeed or fail, no further steps shall be taken.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <b>curpath</b> value shall then be converted to canonical form as follows, considering each component from beginning to end,
|
|
in sequence:</p>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>Dot components and any slashes that separate them from the next component shall be deleted.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>An implementation may further simplify <b>curpath</b> 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 <b>curpath</b> variable is null, no further steps shall be taken.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <i>cd</i> utility shall then perform actions equivalent to the <a href="../functions/chdir.html"><i>chdir</i>()</a> function
|
|
called with <b>curpath</b> as the <i>path</i> argument. If these actions failed for any reason, the <i>cd</i> utility shall display
|
|
an appropriate error message and no further steps shall be taken. The <i>PWD</i> environment variable shall be set to
|
|
<b>curpath</b>.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>If, during the execution of the above steps, the <i>PWD</i> environment variable is changed, the <i>OLDPWD</i> 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 <i>cd</i>).</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>cd</i> utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>.</p>
|
|
|
|
<p>The following options shall be supported by the implementation:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-L</b></dt>
|
|
|
|
<dd>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).</dd>
|
|
|
|
<dt><b>-P</b></dt>
|
|
|
|
<dd>Handle the operand dot-dot physically; symbolic link components shall be resolved before dot-dot components are processed (see
|
|
step 7. in the DESCRIPTION).</dd>
|
|
</dl>
|
|
|
|
<p>If both <b>-L</b> and <b>-P</b> options are specified, the last of these options shall be used and all others ignored. If
|
|
neither <b>-L</b> nor <b>-P</b> is specified, the operand shall be handled dot-dot logically; see the DESCRIPTION.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operands shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>directory</i></dt>
|
|
|
|
<dd>An absolute or relative pathname of the directory that shall become the new working directory. The interpretation of a relative
|
|
pathname by <i>cd</i> depends on the <b>-L</b> option and the <i>CDPATH</i> and <i>PWD</i> environment variables. If
|
|
<i>directory</i> is an empty string, the results are unspecified.</dd>
|
|
|
|
<dt>-</dt>
|
|
|
|
<dd>When a hyphen is used as the operand, this shall be equivalent to the command:
|
|
|
|
<pre>
|
|
<tt>cd "$OLDPWD" && pwd
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>which changes to the previous working directory and then writes its name.</p>
|
|
</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>cd</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>CDPATH</i></dt>
|
|
|
|
<dd>A colon-separated list of pathnames that refer to directories. The <i>cd</i> 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 <i>CDPATH</i> is not set, it shall be treated as if it were an empty string.</dd>
|
|
|
|
<dt><i>HOME</i></dt>
|
|
|
|
<dd>The name of the directory, used when no <i>directory</i> operand is specified.</dd>
|
|
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>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).</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard
|
|
error.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
|
|
<dt><i>OLDPWD</i></dt>
|
|
|
|
<dd>A pathname of the previous working directory, used by <i>cd</i> <b>-</b>.</dd>
|
|
|
|
<dt><i>PWD</i></dt>
|
|
|
|
<dd>This variable shall be set as specified in the DESCRIPTION. If an application sets or unsets the value of <i>PWD ,</i> the
|
|
behavior of <i>cd</i> is unspecified.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>If a non-empty directory name from <i>CDPATH</i> is used, or if <i>cd</i> <b>-</b> is used, an absolute pathname of the new
|
|
working directory shall be written to the standard output as follows:</p>
|
|
|
|
<pre>
|
|
<tt>"%s\n", <</tt><i>new directory</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>Otherwise, there shall be no output.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_11"></a>STDERR</h4>
|
|
|
|
<blockquote>
|
|
<p>The standard error shall be used only for diagnostic messages.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_12"></a>OUTPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_13"></a>EXTENDED DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_14"></a>EXIT STATUS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following exit values shall be returned:</p>
|
|
|
|
<dl compact>
|
|
<dt> 0</dt>
|
|
|
|
<dd>The directory was successfully changed.</dd>
|
|
|
|
<dt>>0</dt>
|
|
|
|
<dd>An error occurred.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_15"></a>CONSEQUENCES OF ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The working directory shall remain unchanged.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_04_15_16"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>Since <i>cd</i> 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:</p>
|
|
|
|
<pre>
|
|
<tt>(cd /tmp)
|
|
nohup cd
|
|
find . -exec cd {} \;
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>it does not affect the working directory of the caller's environment.</p>
|
|
|
|
<p>The user must have execute (search) permission in <i>directory</i> in order to change to it.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_17"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_18"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The use of the <i>CDPATH</i> was introduced in the System V shell. Its use is analogous to the use of the <i>PATH</i> variable
|
|
in the shell. The BSD C shell used a shell parameter <i>cdpath</i> for this purpose.</p>
|
|
|
|
<p>A common extension when <i>HOME</i> is undefined is to get the login directory from the user database for the invoking user.
|
|
This does not occur on System V implementations.</p>
|
|
|
|
<p>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
|
|
<tt>'/'</tt> in the pathname, remembering what the user typed, rather than performing the equivalent of:</p>
|
|
|
|
<pre>
|
|
<tt>chdir("..");
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>In such a shell, the following commands would not necessarily produce equivalent output for all directories:</p>
|
|
|
|
<pre>
|
|
<tt>cd .. && ls ls ..
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>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 <i>PWD</i> environment variable when the <i>cd</i> utility completes and this
|
|
value is used to construct the next directory name if <i>cd</i> is invoked with the <b>-L</b> option.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_19"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_20"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="xcu_chap02.html#tag_02_12"><i>Shell Execution Environment</i></a> , <a href="pwd.html"><i>pwd</i></a> , the System
|
|
Interfaces volume of IEEE Std 1003.1-2001, <a href="../functions/chdir.html"><i>chdir</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_21"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_15_22"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The <i>cd</i> <b>-</b> operand, <i>PWD ,</i> and <i>OLDPWD</i> are added.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The <b>-L</b> and <b>-P</b> options are added to align with the IEEE P1003.2b draft standard. This also includes the
|
|
introduction of a new description to include the effect of these options.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|