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