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
56
57 .SS "sh"
58 .LP
59 .nf
60 \fBcd\fR [\fIargument\fR]
61 .fi
62
63 .LP
64 .nf
65 \fBchdir\fR [\fIargument\fR]
66 .fi
67
68 .SS "csh"
69 .LP
70 .nf
71 \fBcd\fR [\fIdir\fR]
72 .fi
73
74 .LP
75 .nf
76 \fBchdir\fR [\fIdir\fR]
77 .fi
78
79 .LP
80 .nf
81 \fBpushd\fR [\fB+\fR\fIn\fR | \fIdir\fR]
82 .fi
83
84 .LP
85 .nf
86 \fBpopd\fR [\fB+\fR\fIn\fR]
87 .fi
88
89 .LP
90 .nf
91 \fBdirs\fR [\fB-l\fR]
92 .fi
93
94 .SS "ksh, ksh93"
95 .LP
96 .nf
97 \fBcd\fR [\fB-L\fR] [\fB-P\fR] [\fIarg\fR]
98 .fi
99
100 .LP
101 .nf
102 \fBcd\fR \fIold\fR \fInew\fR
103 .fi
104
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
168
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
177
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
190
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
226
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
236
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
267
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
300
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
310
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
319
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
329
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
342
343 .sp
344 .ne 2
345 .na
346 \fB\fB>0\fR\fR
347 .ad
348 .RS 6n
349 An error occurred.
350 .RE
351
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
358
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
370
371 .SS "ksh93"
372 .sp
373
374 .sp
375 .TS
376 box;
377 c | c
378 l | l .
379 ATTRIBUTE TYPE ATTRIBUTE VALUE
380 _
381 Interface Stability Uncommitted
382 .TE
383
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)
|
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 .\" Copyright 2021 OmniOS Community Edition (OmniOSce) Association.
48 .\"
49 .TH CD 1 "Feb 9, 2021"
50 .SH NAME
51 cd, chdir, pushd, popd, dirs \- change working directory
52 .SH SYNOPSIS
53 .nf
54 \fB/usr/bin/cd\fR [\fIdirectory\fR]
55 .fi
56
57 .SS "csh"
58 .nf
59 \fBcd\fR [\fIdir\fR]
60 .fi
61
62 .LP
63 .nf
64 \fBchdir\fR [\fIdir\fR]
65 .fi
66
67 .LP
68 .nf
69 \fBpushd\fR [\fB+\fR\fIn\fR | \fIdir\fR]
70 .fi
71
72 .LP
73 .nf
74 \fBpopd\fR [\fB+\fR\fIn\fR]
75 .fi
76
77 .LP
78 .nf
79 \fBdirs\fR [\fB-l\fR]
80 .fi
81
82 .SS "ksh93"
83 .nf
84 \fBcd\fR [\fB-L\fR] [\fB-P\fR] [\fIarg\fR]
85 .fi
86
87 .LP
88 .nf
89 \fBcd\fR \fIold\fR \fInew\fR
90 .fi
91
92 .SH DESCRIPTION
93 .SS "/usr/bin/cd"
94 The \fB/usr/bin/cd\fR utility changes the current directory in the context of
95 the \fBcd\fR utility only. This is in contrast to the version built into the
96 shell. \fB/usr/bin/cd\fR has no effect on the invoking process but can be used
97 to determine whether or not a given directory can be set as the current
98 directory.
99 .SS "csh"
100 If \fIdir\fR is not specified, the C shell built-in \fBcd\fR uses the value of
101 shell parameter \fBHOME\fR as the new working directory. If \fIdir\fR specifies
102 a complete path starting with `\fB/\fR', `\fB\&.\fR', or `\fB\&.\|.\fR',
103 \fIdir\fR becomes the new working directory. If neither case applies, \fBcd\fR
104 tries to find the designated directory relative to one of the paths specified
105 by the \fBCDPATH\fR shell variable. \fBCDPATH\fR has the same syntax as, and
106 similar semantics to, the \fBPATH\fR shell variable. \fBcd\fR must have execute
107 (search) permission in \fIdir\fR. Because a new process is created to execute
108 each command, \fBcd\fR would be ineffective if it were written as a normal
109 command; therefore, it is recognized by and is internal to the C-shell. (See
110 \fBpwd\fR(1), \fBsh\fR(1), and \fBchdir\fR(2)).
111 .sp
112 .LP
113 \fBchdir\fR changes the shell's working directory to directory \fIdir\fR. If no
114 argument is given, change to the home directory of the user. If \fIdir\fR is a
115 relative pathname not found in the current directory, check for it in those
116 directories listed in the \fBcdpath\fR variable. If \fIdir\fR is the name of a
117 shell variable whose value starts with a \fB/\fR, change to the directory named
118 by that value.
119 .sp
120 .LP
121 \fBpushd\fR pushes a directory onto the directory stack. With no arguments,
122 exchange the top two elements.
123 .sp
124 .ne 2
125 .na
126 \fB+\fR\fIn\fR
127 .ad
128 .RS 7n
129 Rotate the \fIn\fR'th entry to the top of the stack and \fBcd\fR to it.
130 .RE
131
132 .sp
133 .ne 2
134 .na
135 \fB\fIdir\fR
136 .ad
137 .RS 7n
138 Push the current working directory onto the stack and change to \fIdir\fR.
139 .RE
140
141 .sp
142 .LP
143 \fBpopd\fR pops the directory stack and \fBcd\fR to the new top directory. The
144 elements of the directory stack are numbered from 0 starting at the top.
145 .sp
146 .ne 2
147 .na
148 \fB+\fR\fIn\fR
149 .ad
150 .RS 6n
151 Discard the \fIn\fR'th entry in the stack.
152 .RE
153
154 .sp
155 .LP
156 \fBdirs\fR prints the directory stack, most recent to the left; the first
157 directory shown is the current directory. With the \fB-l\fR argument, produce
158 an unabbreviated printout; use of the \fB~\fR notation is suppressed.
159 .SS "ksh93"
160 The Korn shell built-in \fBcd\fR command can be in either of two forms. In the
161 first form it changes the current directory to \fIarg\fR. If \fIarg\fR is
162 \fB\(mi\fR the directory is changed to the previous directory. The shell
163 variable \fBHOME\fR is the default \fIarg\fR. The environment variable
164 \fBPWD\fR is set to the current directory. If the \fBPWD\fR is changed, the
165 \fBOLDPWD\fR environment variable shall also be changed to the value of the old
166 working directory, that is, the current working directory immediately prior to
167 the call to change directory (\fBcd\fR). The shell variable \fBCDPATH\fR
168 defines the search path for the directory containing \fIarg\fR. Alternative
169 directory names are separated by a colon (\fB:\fR). The default path is
170 \fBnull\fR (specifying the current directory). The current directory is
171 specified by a null path name, which can appear immediately after the equal
172 sign or between the colon delimiters anywhere else in the path list. If
173 \fIarg\fR begins with a `\fB/\fR', `\fB\&.\fR', or `\fB\&.\|.\fR', then the
174 search path is not used. Otherwise, each directory in the path is searched for
175 \fIarg\fR. If unsuccessful, \fBcd\fR attempts to change directories to the
176 pathname formed by the concatenation of the value of PWD, a slash character,
177 and arg.
178 .sp
179 .ne 2
180 .na
181 \fB-L\fR
182 .ad
183 .RS 6n
184 Handles the operation dot-dot (\fB\&..\fR) logically. Symbolic link components
185 are \fBnot\fR resolved before dot-dot components are processed.
186 .RE
187
188 .sp
189 .ne 2
190 .na
191 \fB-P\fR
192 .ad
193 .RS 6n
194 Handles the operand dot-dot physically. Symbolic link components \fBare\fR
195 resolved before dot-dot components are processed.
196 .RE
197
198 .sp
199 .LP
200 If both \fB-L\fR and \fB-P\fR options are specified, the last option to be
201 invoked is used and the other is ignored. If neither \fB-L\fR nor \fB-P\fR is
202 specified, the operand is handled dot-dot logically.
203 .sp
204 .LP
205 The second form of \fBcd\fR substitutes the string \fInew\fR for the string
206 \fIold\fR in the current directory name, \fBPWD\fR and tries to change to this
207 new directory.
208 .sp
209 .LP
210 The \fBcd\fR command cannot be executed by \fBrksh\fR. Because a new process is
211 created to execute each command, \fBcd\fR would be ineffective if it were
212 written as a normal command; therefore, it is recognized by and is internal to
213 the Korn shell. (See \fBpwd\fR(1), \fBksh93\fR(1), and \fBchdir\fR(2)).
214 .SH OPERANDS
215 The following operands are supported:
216 .sp
217 .ne 2
218 .na
219 \fB\fIdirectory\fR
220 .ad
221 .RS 13n
222 An absolute or relative pathname of the directory that becomes the new working
223 directory. The interpretation of a relative pathname by \fBcd\fR depends on the
224 \fBCDPATH\fR environment variable.
225 .RE
226
227 .SH OUTPUT
228 If a non-empty directory name from \fBCDPATH\fR is used, an absolute pathname
229 of the new working directory is written to the standard output as follows:
230 .sp
231 .LP
232 \fB"%s\en"\fR, <\fInew directory\fR>
233 .sp
234 .LP
235 Otherwise, there is no output.
236 .SH ENVIRONMENT VARIABLES
237 See \fBenviron\fR(5) for descriptions of the following environment variables
238 that affect the execution of \fBcd\fR: \fBLANG\fR, \fBLC_ALL\fR,
239 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
240 .sp
241 .ne 2
242 .na
243 \fBCDPATH\fR
244 .ad
245 .RS 10n
246 A colon-separated list of pathnames that refer to directories. If the
247 \fIdirectory\fR operand does not begin with a slash \fB(\fR \fB/\fR \fB)\fR
248 character, and the first component is not dot or dot-dot, \fBcd\fR searches for
249 \fIdirectory\fR relative to each directory named in the \fBCDPATH\fR variable,
250 in the order listed. The new working directory sets to the first matching
251 directory found. An empty string in place of a directory pathname represents
252 the current directory. If \fBCDPATH\fR is not set, it is treated as if it were
253 an empty string.
254 .RE
255
256 .sp
257 .ne 2
258 .na
259 \fBHOME\fR
260 .ad
261 .RS 10n
262 The name of the home directory, used when no \fIdirectory\fR operand is
263 specified.
264 .RE
265
266 .sp
267 .ne 2
268 .na
269 \fBOLDPWD\fR
270 .ad
271 .RS 10n
272 A pathname of the previous working directory, used by \fBcd-\fR.
273 .RE
274
275 .sp
276 .ne 2
277 .na
278 \fBPWD\fR
279 .ad
280 .RS 10n
281 A pathname of the current working directory, set by \fBcd\fR after it has
282 changed to that directory.
283 .RE
284
285 .SH EXIT STATUS
286 The following exit values are returned by \fBcd\fR:
287 .sp
288 .ne 2
289 .na
290 \fB0\fR
291 .ad
292 .RS 6n
293 The directory was successfully changed.
294 .RE
295
296 .sp
297 .ne 2
298 .na
299 \fB>0\fR
300 .ad
301 .RS 6n
302 An error occurred.
303 .RE
304
305 .SH ATTRIBUTES
306 See \fBattributes\fR(5) for descriptions of the following attributes:
307 .SS "csh"
308 .TS
309 box;
310 c | c
311 l | l .
312 ATTRIBUTE TYPE ATTRIBUTE VALUE
313 _
314 Interface Stability Committed
315 _
316 Standard See \fBstandards\fR(5).
317 .TE
318
319 .SS "ksh93"
320 .TS
321 box;
322 c | c
323 l | l .
324 ATTRIBUTE TYPE ATTRIBUTE VALUE
325 _
326 Interface Stability Uncommitted
327 .TE
328
329 .SH SEE ALSO
330 \fBcsh\fR(1), \fBksh93\fR(1), \fBpwd\fR(1),
331 \fBchdir\fR(2), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)
|