| blob | 08f46a9c8785de97179882f8ee92c570e8998029 |
1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
4 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
5 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
7 .\" http://www.opengroup.org/bookstore/.
8 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.
9 .\" This notice shall appear on any product containing this material.
10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
11 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
12 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 .TH CD 1 "Apr 8, 2008"
14 .SH NAME
15 cd, chdir, pushd, popd, dirs \- change working directory
16 .SH SYNOPSIS
17 .LP
18 .nf
19 \fB/usr/bin/cd\fR [\fIdirectory\fR]
20 .fi
22 .SS "sh"
23 .LP
24 .nf
25 \fBcd\fR [\fIargument\fR]
26 .fi
28 .LP
29 .nf
30 \fBchdir\fR [\fIargument\fR]
31 .fi
33 .SS "csh"
34 .LP
35 .nf
36 \fBcd\fR [\fIdir\fR]
37 .fi
39 .LP
40 .nf
41 \fBchdir\fR [\fIdir\fR]
42 .fi
44 .LP
45 .nf
46 \fBpushd\fR [\fB+\fR\fIn\fR | \fIdir\fR]
47 .fi
49 .LP
50 .nf
51 \fBpopd\fR [\fB+\fR\fIn\fR]
52 .fi
54 .LP
55 .nf
56 \fBdirs\fR [\fB-l\fR]
57 .fi
59 .SS "ksh, ksh93"
60 .LP
61 .nf
62 \fBcd\fR [\fB-L\fR] [\fB-P\fR] [\fIarg\fR]
63 .fi
65 .LP
66 .nf
67 \fBcd\fR \fIold\fR \fInew\fR
68 .fi
70 .SH DESCRIPTION
71 .SS "/usr/bin/cd"
72 .sp
73 .LP
74 The \fB/usr/bin/cd\fR utility changes the current directory in the context of
75 the \fBcd\fR utility only. This is in contrast to the version built into the
76 shell. \fB/usr/bin/cd\fR has no effect on the invoking process but can be used
77 to determine whether or not a given directory can be set as the current
78 directory.
79 .SS "sh"
80 .sp
81 .LP
82 The Bourne shell built-in \fBcd\fR changes the current directory to
83 \fIargument\fR. The shell parameter \fBHOME\fR is the default \fIargument\fR.
84 The shell parameter \fBCDPATH\fR defines the search path for the directory
85 containing \fIargument\fR. Alternative directory names are separated by a colon
86 (\fB:\fR). The default path is \fB<null>\fR (specifying the current directory).
87 The current directory is specified by a null path name, which can appear
88 immediately after the equal sign or between the colon delimiters anywhere else
89 in the path list. If \fIargument\fR begins with `\fB/\fR', `\fB\&.\fR', or
90 `\fB\&.\|.\fR', the search path is not used. Otherwise, each directory in the
91 path is searched for \fIargument\fR. \fBcd\fR must have execute (search)
92 permission in \fIargument\fR. Because a new process is created to execute each
93 command, \fBcd\fR would be ineffective if it were written as a normal command;
94 therefore, it is recognized by and is internal to the shell. (See \fBpwd\fR(1),
95 \fBsh\fR(1), and \fBchdir\fR(2)).
96 .sp
97 .LP
98 \fBchdir\fR is just another way to call \fBcd\fR.
99 .SS "csh"
100 .sp
101 .LP
102 If \fIdir\fR is not specified, the C shell built-in \fBcd\fR uses the value of
103 shell parameter \fBHOME\fR as the new working directory. If \fIdir\fR specifies
104 a complete path starting with `\fB/\fR', `\fB\&.\fR', or `\fB\&.\|.\fR',
105 \fIdir\fR becomes the new working directory. If neither case applies, \fBcd\fR
106 tries to find the designated directory relative to one of the paths specified
107 by the \fBCDPATH\fR shell variable. \fBCDPATH\fR has the same syntax as, and
108 similar semantics to, the \fBPATH\fR shell variable. \fBcd\fR must have execute
109 (search) permission in \fIdir\fR. Because a new process is created to execute
110 each command, \fBcd\fR would be ineffective if it were written as a normal
111 command; therefore, it is recognized by and is internal to the C-shell. (See
112 \fBpwd\fR(1), \fBsh\fR(1), and \fBchdir\fR(2)).
113 .sp
114 .LP
115 \fBchdir\fR changes the shell's working directory to directory \fIdir\fR. If no
116 argument is given, change to the home directory of the user. If \fIdir\fR is a
117 relative pathname not found in the current directory, check for it in those
118 directories listed in the \fBcdpath\fR variable. If \fIdir\fR is the name of a
119 shell variable whose value starts with a \fB/\fR, change to the directory named
120 by that value.
121 .sp
122 .LP
123 \fBpushd\fR pushes a directory onto the directory stack. With no arguments,
124 exchange the top two elements.
125 .sp
126 .ne 2
127 .na
128 \fB\fB+\fR\fIn\fR\fR
129 .ad
130 .RS 7n
131 Rotate the \fIn\fR'th entry to the top of the stack and \fBcd\fR to it.
132 .RE
134 .sp
135 .ne 2
136 .na
137 \fB\fIdir\fR\fR
138 .ad
139 .RS 7n
140 Push the current working directory onto the stack and change to \fIdir\fR.
141 .RE
143 .sp
144 .LP
145 \fBpopd\fR pops the directory stack and \fBcd\fR to the new top directory. The
146 elements of the directory stack are numbered from 0 starting at the top.
147 .sp
148 .ne 2
149 .na
150 \fB\fB+\fR\fIn\fR\fR
151 .ad
152 .RS 6n
153 Discard the \fIn\fR'th entry in the stack.
154 .RE
156 .sp
157 .LP
158 \fBdirs\fR prints the directory stack, most recent to the left; the first
159 directory shown is the current directory. With the \fB-l\fR argument, produce
160 an unabbreviated printout; use of the \fB~\fR notation is suppressed.
161 .SS "ksh, ksh93"
162 .sp
163 .LP
164 The Korn shell built-in \fBcd\fR command can be in either of two forms. In the
165 first form it changes the current directory to \fIarg\fR. If \fIarg\fR is
166 \fB\(mi\fR the directory is changed to the previous directory. The shell
167 variable \fBHOME\fR is the default \fIarg\fR. The environment variable
168 \fBPWD\fR is set to the current directory. If the \fBPWD\fR is changed, the
169 \fBOLDPWD\fR environment variable shall also be changed to the value of the old
170 working directory, that is, the current working directory immediately prior to
171 the call to change directory (\fBcd\fR). The shell variable \fBCDPATH\fR
172 defines the search path for the directory containing \fIarg\fR. Alternative
173 directory names are separated by a colon (\fB:\fR). The default path is
174 \fBnull\fR (specifying the current directory). The current directory is
175 specified by a null path name, which can appear immediately after the equal
176 sign or between the colon delimiters anywhere else in the path list. If
177 \fIarg\fR begins with a `\fB/\fR', `\fB\&.\fR', or `\fB\&.\|.\fR', then the
178 search path is not used. Otherwise, each directory in the path is searched for
179 \fIarg\fR. If unsuccessful, \fBcd\fR attempts to change directories to the
180 pathname formed by the concatenation of the value of PWD, a slash character,
181 and arg.
182 .sp
183 .ne 2
184 .na
185 \fB\fB-L\fR\fR
186 .ad
187 .RS 6n
188 Handles the operation dot-dot (\fB\&..\fR) logically. Symbolic link components
189 are \fBnot\fR resolved before dot-dot components are processed.
190 .RE
192 .sp
193 .ne 2
194 .na
195 \fB\fB-P\fR\fR
196 .ad
197 .RS 6n
198 Handles the operand dot-dot physically. Symbolic link components \fBare\fR
199 resolved before dot-dot components are processed.
200 .RE
202 .sp
203 .LP
204 If both \fB-L\fR and \fB-P\fR options are specified, the last option to be
205 invoked is used and the other is ignored. If neither \fB-L\fR nor \fB-P\fR is
206 specified, the operand is handled dot-dot logically.
207 .sp
208 .LP
209 The second form of \fBcd\fR substitutes the string \fInew\fR for the string
210 \fIold\fR in the current directory name, \fBPWD\fR and tries to change to this
211 new directory.
212 .sp
213 .LP
214 The \fBcd\fR command cannot be executed by \fBrksh\fR. Because a new process is
215 created to execute each command, \fBcd\fR would be ineffective if it were
216 written as a normal command; therefore, it is recognized by and is internal to
217 the Korn shell. (See \fBpwd\fR(1), \fBsh\fR(1), and \fBchdir\fR(2)).
218 .SH OPERANDS
219 .sp
220 .LP
221 The following operands are supported:
222 .sp
223 .ne 2
224 .na
225 \fB\fIdirectory\fR\fR
226 .ad
227 .RS 13n
228 An absolute or relative pathname of the directory that becomes the new working
229 directory. The interpretation of a relative pathname by \fBcd\fR depends on the
230 \fBCDPATH\fR environment variable.
231 .RE
233 .SH OUTPUT
234 .sp
235 .LP
236 If a non-empty directory name from \fBCDPATH\fR is used, an absolute pathname
237 of the new working directory is written to the standard output as follows:
238 .sp
239 .LP
240 \fB"%s\en"\fR, <\fInew directory\fR>
241 .sp
242 .LP
243 Otherwise, there is no output.
244 .SH ENVIRONMENT VARIABLES
245 .sp
246 .LP
247 See \fBenviron\fR(5) for descriptions of the following environment variables
248 that affect the execution of \fBcd\fR: \fBLANG\fR, \fBLC_ALL\fR,
249 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
250 .sp
251 .ne 2
252 .na
253 \fB\fBCDPATH\fR\fR
254 .ad
255 .RS 10n
256 A colon-separated list of pathnames that refer to directories. If the
257 \fIdirectory\fR operand does not begin with a slash \fB(\fR \fB/\fR \fB)\fR
258 character, and the first component is not dot or dot-dot, \fBcd\fR searches for
259 \fIdirectory\fR relative to each directory named in the \fBCDPATH\fR variable,
260 in the order listed. The new working directory sets to the first matching
261 directory found. An empty string in place of a directory pathname represents
262 the current directory. If \fBCDPATH\fR is not set, it is treated as if it were
263 an empty string.
264 .RE
266 .sp
267 .ne 2
268 .na
269 \fB\fBHOME\fR\fR
270 .ad
271 .RS 10n
272 The name of the home directory, used when no \fIdirectory\fR operand is
273 specified.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fBOLDPWD\fR\fR
280 .ad
281 .RS 10n
282 A pathname of the previous working directory, used by \fBcd-\fR.
283 .RE
285 .sp
286 .ne 2
287 .na
288 \fB\fBPWD\fR\fR
289 .ad
290 .RS 10n
291 A pathname of the current working directory, set by \fBcd\fR after it has
292 changed to that directory.
293 .RE
295 .SH EXIT STATUS
296 .sp
297 .LP
298 The following exit values are returned by \fBcd\fR:
299 .sp
300 .ne 2
301 .na
302 \fB\fB0\fR\fR
303 .ad
304 .RS 6n
305 The directory was successfully changed.
306 .RE
308 .sp
309 .ne 2
310 .na
311 \fB\fB>0\fR\fR
312 .ad
313 .RS 6n
314 An error occurred.
315 .RE
317 .SH ATTRIBUTES
318 .sp
319 .LP
320 See \fBattributes\fR(5) for descriptions of the following attributes:
321 .SS "csh, ksh, sh"
322 .sp
324 .sp
325 .TS
326 box;
327 c | c
328 l | l .
329 ATTRIBUTE TYPE ATTRIBUTE VALUE
330 _
331 Interface Stability Committed
332 _
333 Standard See \fBstandards\fR(5).
334 .TE
336 .SS "ksh93"
337 .sp
339 .sp
340 .TS
341 box;
342 c | c
343 l | l .
344 ATTRIBUTE TYPE ATTRIBUTE VALUE
345 _
346 Interface Stability Uncommitted
347 .TE
349 .SH SEE ALSO
350 .sp
351 .LP
352 \fBcsh\fR(1), \fBksh\fR(1), \fBksh93\fR(1), \fBpwd\fR(1), \fBsh\fR(1),
353 \fBchdir\fR(2), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)