logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

cd.1p (13172B)


  1. '\" et
  2. .TH CD "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. cd
  12. \(em change the working directory
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. cd \fB[\fR-L|-P\fB] [\fIdirectory\fB]\fR
  17. .P
  18. cd -
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. .IR cd
  23. utility shall change the working directory of the current shell
  24. execution environment (see
  25. .IR "Section 2.12" ", " "Shell Execution Environment")
  26. by executing the following steps in sequence. (In the following steps,
  27. the symbol
  28. .BR curpath
  29. represents an intermediate value used to simplify the description of
  30. the algorithm used by
  31. .IR cd .
  32. There is no requirement that
  33. .BR curpath
  34. be made visible to the application.)
  35. .IP " 1." 4
  36. If no
  37. .IR directory
  38. operand is given and the
  39. .IR HOME
  40. environment variable is empty or undefined, the default behavior is
  41. implementation-defined and no further steps shall be taken.
  42. .IP " 2." 4
  43. If no
  44. .IR directory
  45. operand is given and the
  46. .IR HOME
  47. environment variable is set to a non-empty value, the
  48. .IR cd
  49. utility shall behave as if the directory named in the
  50. .IR HOME
  51. environment variable was specified as the
  52. .IR directory
  53. operand.
  54. .IP " 3." 4
  55. If the
  56. .IR directory
  57. operand begins with a
  58. <slash>
  59. character, set
  60. .BR curpath
  61. to the operand and proceed to step 7.
  62. .IP " 4." 4
  63. If the first component of the
  64. .IR directory
  65. operand is dot or dot-dot, proceed to step 6.
  66. .IP " 5." 4
  67. Starting with the first pathname in the
  68. <colon>-separated
  69. pathnames of
  70. .IR CDPATH
  71. (see the ENVIRONMENT VARIABLES section) if the pathname is non-null,
  72. test if the concatenation of that pathname, a
  73. <slash>
  74. character if that pathname did not end with a
  75. <slash>
  76. character, and the
  77. .IR directory
  78. operand names a directory. If the pathname is null, test if the
  79. concatenation of dot, a
  80. <slash>
  81. character, and the operand names a directory. In either case, if the
  82. resulting string names an existing directory, set
  83. .BR curpath
  84. to that string and proceed to step 7. Otherwise, repeat this step with
  85. the next pathname in
  86. .IR CDPATH
  87. until all pathnames have been tested.
  88. .IP " 6." 4
  89. Set
  90. .BR curpath
  91. to the
  92. .IR directory
  93. operand.
  94. .IP " 7." 4
  95. If the
  96. .BR \-P
  97. option is in effect, proceed to step 10. If
  98. .BR curpath
  99. does not begin with a
  100. <slash>
  101. character, set
  102. .BR curpath
  103. to the string formed by the concatenation of the value of
  104. .IR PWD ,
  105. a
  106. <slash>
  107. character if the value of
  108. .IR PWD
  109. did not end with a
  110. <slash>
  111. character, and
  112. .BR curpath .
  113. .IP " 8." 4
  114. The
  115. .BR curpath
  116. value shall then be converted to canonical form as follows, considering
  117. each component from beginning to end, in sequence:
  118. .RS 4
  119. .IP " a." 4
  120. Dot components and any
  121. <slash>
  122. characters that separate them from the next component shall be deleted.
  123. .IP " b." 4
  124. For each dot-dot component, if there is a preceding component and it is
  125. neither root nor dot-dot, then:
  126. .RS 4
  127. .IP " i." 5
  128. If the preceding component does not refer (in the context of pathname
  129. resolution with symbolic links followed) to a directory, then the
  130. .IR cd
  131. utility shall display an appropriate error message and no further steps
  132. shall be taken.
  133. .IP ii. 5
  134. The preceding component, all
  135. <slash>
  136. characters separating the preceding component from dot-dot, dot-dot,
  137. and all
  138. <slash>
  139. characters separating dot-dot from the following component (if any)
  140. shall be deleted.
  141. .RE
  142. .IP " c." 4
  143. An implementation may further simplify
  144. .BR curpath
  145. by removing any trailing
  146. <slash>
  147. characters that are not also leading
  148. <slash>
  149. characters, replacing multiple non-leading consecutive
  150. <slash>
  151. characters with a single
  152. <slash>,
  153. and replacing three or more leading
  154. <slash>
  155. characters with a single
  156. <slash>.
  157. If, as a result of this canonicalization, the
  158. .BR curpath
  159. variable is null, no further steps shall be taken.
  160. .RE
  161. .IP " 9." 4
  162. If
  163. .BR curpath
  164. is longer than
  165. {PATH_MAX}
  166. bytes (including the terminating null) and the
  167. .IR directory
  168. operand was not longer than
  169. {PATH_MAX}
  170. bytes (including the terminating null), then
  171. .BR curpath
  172. shall be converted from an absolute pathname to an equivalent relative
  173. pathname if possible. This conversion shall always be considered
  174. possible if the value of
  175. .IR PWD ,
  176. with a trailing
  177. <slash>
  178. added if it does not already have one, is an initial substring of
  179. .BR curpath .
  180. Whether or not it is considered possible under other circumstances is
  181. unspecified. Implementations may also apply this conversion if
  182. .BR curpath
  183. is not longer than
  184. {PATH_MAX}
  185. bytes or the
  186. .IR directory
  187. operand was longer than
  188. {PATH_MAX}
  189. bytes.
  190. .IP 10. 4
  191. The
  192. .IR cd
  193. utility shall then perform actions equivalent to the
  194. \fIchdir\fR()
  195. function called with
  196. .BR curpath
  197. as the
  198. .IR path
  199. argument. If these actions fail for any reason, the
  200. .IR cd
  201. utility shall display an appropriate error message and the remainder of
  202. this step shall not be executed. If the
  203. .BR \-P
  204. option is not in effect, the
  205. .IR PWD
  206. environment variable shall be set to the value that
  207. .BR curpath
  208. had on entry to step 9 (i.e., before conversion to a relative
  209. pathname). If the
  210. .BR \-P
  211. option is in effect, the
  212. .IR PWD
  213. environment variable shall be set to the string that would be output by
  214. .IR pwd
  215. .BR \-P .
  216. If there is insufficient permission on the new directory, or on any
  217. parent of that directory, to determine the current working directory,
  218. the value of the
  219. .IR PWD
  220. environment variable is unspecified.
  221. .P
  222. If, during the execution of the above steps, the
  223. .IR PWD
  224. environment variable
  225. is set, the
  226. .IR OLDPWD
  227. environment variable shall also be set to
  228. the value of the old working directory (that is the current working
  229. directory immediately prior to the call to
  230. .IR cd ).
  231. .SH OPTIONS
  232. The
  233. .IR cd
  234. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  235. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  236. .P
  237. The following options shall be supported by the implementation:
  238. .IP "\fB\-L\fP" 10
  239. Handle the operand dot-dot logically; symbolic link components shall
  240. not be resolved before dot-dot components are processed (see steps 8.
  241. and 9. in the DESCRIPTION).
  242. .IP "\fB\-P\fP" 10
  243. Handle the operand dot-dot physically; symbolic link components shall
  244. be resolved before dot-dot components are processed (see step 7. in the
  245. DESCRIPTION).
  246. .P
  247. If both
  248. .BR \-L
  249. and
  250. .BR \-P
  251. options are specified, the last of these options shall be used and all
  252. others ignored. If neither
  253. .BR \-L
  254. nor
  255. .BR \-P
  256. is specified, the operand shall be handled dot-dot logically; see the
  257. DESCRIPTION.
  258. .SH OPERANDS
  259. The following operands shall be supported:
  260. .IP "\fIdirectory\fR" 10
  261. An absolute or relative pathname of the directory that shall become
  262. the new working directory. The interpretation of a relative pathname
  263. by
  264. .IR cd
  265. depends on the
  266. .BR \-L
  267. option and the
  268. .IR CDPATH
  269. and
  270. .IR PWD
  271. environment variables. If
  272. .IR directory
  273. is an empty string, the results are unspecified.
  274. .IP "\-" 10
  275. When a
  276. <hyphen-minus>
  277. is used as the operand, this shall be equivalent to the command:
  278. .RS 10
  279. .sp
  280. .RS 4
  281. .nf
  282. cd "$OLDPWD" && pwd
  283. .fi
  284. .P
  285. .RE
  286. .P
  287. which changes to the previous working directory and then writes its
  288. name.
  289. .RE
  290. .SH STDIN
  291. Not used.
  292. .SH "INPUT FILES"
  293. None.
  294. .SH "ENVIRONMENT VARIABLES"
  295. The following environment variables shall affect the execution of
  296. .IR cd :
  297. .IP "\fICDPATH\fP" 10
  298. A
  299. <colon>-separated
  300. list of pathnames that refer to directories. The
  301. .IR cd
  302. utility shall use this list in its attempt to change the directory, as
  303. described in the DESCRIPTION. An empty string in place of a directory
  304. pathname represents the current directory. If
  305. .IR CDPATH
  306. is not set, it shall be treated as if it were an empty string.
  307. .IP "\fIHOME\fP" 10
  308. The name of the directory, used when no
  309. .IR directory
  310. operand is specified.
  311. .IP "\fILANG\fP" 10
  312. Provide a default value for the internationalization variables that are
  313. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  314. .IR "Section 8.2" ", " "Internationalization Variables"
  315. for the precedence of internationalization variables used to determine
  316. the values of locale categories.)
  317. .IP "\fILC_ALL\fP" 10
  318. If set to a non-empty string value, override the values of all the
  319. other internationalization variables.
  320. .IP "\fILC_CTYPE\fP" 10
  321. Determine the locale for the interpretation of sequences of bytes of
  322. text data as characters (for example, single-byte as opposed to
  323. multi-byte characters in arguments).
  324. .IP "\fILC_MESSAGES\fP" 10
  325. .br
  326. Determine the locale that should be used to affect the format and
  327. contents of diagnostic messages written to standard error.
  328. .IP "\fINLSPATH\fP" 10
  329. Determine the location of message catalogs for the processing of
  330. .IR LC_MESSAGES .
  331. .IP "\fIOLDPWD\fP" 10
  332. A pathname of the previous working directory, used by
  333. .IR cd
  334. .BR \- .
  335. .IP "\fIPWD\fP" 10
  336. This variable shall be set as specified in the DESCRIPTION. If an
  337. application sets or unsets the value of
  338. .IR PWD ,
  339. the behavior of
  340. .IR cd
  341. is unspecified.
  342. .SH "ASYNCHRONOUS EVENTS"
  343. Default.
  344. .SH STDOUT
  345. If a non-empty directory name from
  346. .IR CDPATH
  347. is used, or if
  348. .IR cd
  349. .BR \-
  350. is used, an absolute pathname of the new working directory shall be
  351. written to the standard output as follows:
  352. .sp
  353. .RS 4
  354. .nf
  355. "%s\en", <\fInew directory\fR>
  356. .fi
  357. .P
  358. .RE
  359. .P
  360. Otherwise, there shall be no output.
  361. .SH STDERR
  362. The standard error shall be used only for diagnostic messages.
  363. .SH "OUTPUT FILES"
  364. None.
  365. .SH "EXTENDED DESCRIPTION"
  366. None.
  367. .SH "EXIT STATUS"
  368. The following exit values shall be returned:
  369. .IP "\00" 6
  370. The directory was successfully changed.
  371. .IP >0 6
  372. An error occurred.
  373. .SH "CONSEQUENCES OF ERRORS"
  374. The working directory shall remain unchanged.
  375. .LP
  376. .IR "The following sections are informative."
  377. .SH "APPLICATION USAGE"
  378. Since
  379. .IR cd
  380. affects the current shell execution environment, it is always provided
  381. as a shell regular built-in. If it is called in a subshell or separate
  382. utility execution environment, such as one of the following:
  383. .sp
  384. .RS 4
  385. .nf
  386. (cd /tmp)
  387. nohup cd
  388. find . -exec cd {} \e;
  389. .fi
  390. .P
  391. .RE
  392. .P
  393. it does not affect the working directory of the caller's environment.
  394. .P
  395. The user must have execute (search) permission in
  396. .IR directory
  397. in order to change to it.
  398. .SH EXAMPLES
  399. The following template can be used to perform processing in the directory
  400. specified by
  401. .IR location
  402. and end up in the current working directory in use before the first
  403. .IR cd
  404. command was issued:
  405. .sp
  406. .RS 4
  407. .nf
  408. cd \fIlocation\fP
  409. if [ $? -ne 0 ]
  410. then
  411. print error message
  412. exit 1
  413. fi
  414. \&... do whatever is desired as long as the OLDPWD environment variable
  415. is not modified
  416. cd -
  417. .fi
  418. .P
  419. .RE
  420. .SH RATIONALE
  421. The use of the
  422. .IR CDPATH
  423. was introduced in the System V shell. Its use is analogous to the use
  424. of the
  425. .IR PATH
  426. variable in the shell. The BSD C shell used a shell parameter
  427. .IR cdpath
  428. for this purpose.
  429. .P
  430. A common extension when
  431. .IR HOME
  432. is undefined is to get the login directory from the user database for
  433. the invoking user. This does not occur on System V implementations.
  434. .P
  435. Some historical shells, such as the KornShell, took special actions
  436. when the directory name contained a dot-dot component, selecting the
  437. logical parent of the directory, rather than the actual parent
  438. directory; that is, it moved up one level toward the
  439. .BR '/'
  440. in the pathname, remembering what the user typed, rather than
  441. performing the equivalent of:
  442. .sp
  443. .RS 4
  444. .nf
  445. chdir("..");
  446. .fi
  447. .P
  448. .RE
  449. .P
  450. In such a shell, the following commands would not necessarily produce
  451. equivalent output for all directories:
  452. .sp
  453. .RS 4
  454. .nf
  455. cd .. && ls ls ..
  456. .fi
  457. .P
  458. .RE
  459. .P
  460. This behavior is now the default. It is not consistent with the
  461. definition of dot-dot in most historical practice; that is, while this
  462. behavior has been optionally available in the KornShell, other shells
  463. have historically not supported this functionality. The logical
  464. pathname is stored in the
  465. .IR PWD
  466. environment variable when the
  467. .IR cd
  468. utility completes and this value is used to construct the next
  469. directory name if
  470. .IR cd
  471. is invoked with the
  472. .BR \-L
  473. option.
  474. .SH "FUTURE DIRECTIONS"
  475. None.
  476. .SH "SEE ALSO"
  477. .IR "Section 2.12" ", " "Shell Execution Environment",
  478. .IR "\fIpwd\fR\^"
  479. .P
  480. The Base Definitions volume of POSIX.1\(hy2017,
  481. .IR "Chapter 8" ", " "Environment Variables",
  482. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  483. .P
  484. The System Interfaces volume of POSIX.1\(hy2017,
  485. .IR "\fIchdir\fR\^(\|)"
  486. .\"
  487. .SH COPYRIGHT
  488. Portions of this text are reprinted and reproduced in electronic form
  489. from IEEE Std 1003.1-2017, Standard for Information Technology
  490. -- Portable Operating System Interface (POSIX), The Open Group Base
  491. Specifications Issue 7, 2018 Edition,
  492. Copyright (C) 2018 by the Institute of
  493. Electrical and Electronics Engineers, Inc and The Open Group.
  494. In the event of any discrepancy between this version and the original IEEE and
  495. The Open Group Standard, the original IEEE and The Open Group Standard
  496. is the referee document. The original Standard can be obtained online at
  497. http://www.opengroup.org/unix/online.html .
  498. .PP
  499. Any typographical or formatting errors that appear
  500. in this page are most likely
  501. to have been introduced during the conversion of the source files to
  502. man page format. To report such errors, see
  503. https://www.kernel.org/doc/man-pages/reporting_bugs.html .