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

rename.3p (13771B)


  1. '\" et
  2. .TH RENAME "3P" 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. rename, renameat
  12. \(em rename file
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. .P
  18. int rename(const char *\fIold\fP, const char *\fInew\fP);
  19. .P
  20. #include <fcntl.h>
  21. .P
  22. int renameat(int \fIoldfd\fP, const char *\fIold\fP, int \fInewfd\fP,
  23. const char *\fInew\fP);
  24. .fi
  25. .SH DESCRIPTION
  26. For
  27. \fIrename\fR():
  28. The functionality described on this reference page is aligned with the
  29. ISO\ C standard. Any conflict between the requirements described here and the
  30. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  31. .P
  32. The
  33. \fIrename\fR()
  34. function shall change the name of a file. The
  35. .IR old
  36. argument points to the pathname of the file to be renamed. The
  37. .IR new
  38. argument points to the new pathname of the file.
  39. If the
  40. .IR new
  41. argument does not resolve to an existing directory entry for a file of
  42. type directory and the
  43. .IR new
  44. argument contains at least one non-\c
  45. <slash>
  46. character and ends with one or more trailing
  47. <slash>
  48. characters after all symbolic links have been processed,
  49. \fIrename\fR()
  50. shall fail.
  51. .P
  52. If either the
  53. .IR old
  54. or
  55. .IR new
  56. argument names a symbolic link,
  57. \fIrename\fR()
  58. shall operate on the symbolic link itself, and shall not resolve the
  59. last component of the argument. If the
  60. .IR old
  61. argument and the
  62. .IR new
  63. argument resolve to either the same existing directory entry or different
  64. directory entries for the same existing file,
  65. \fIrename\fR()
  66. shall return successfully and perform no other action.
  67. .P
  68. If the
  69. .IR old
  70. argument points to the pathname of a file that is not a directory, the
  71. .IR new
  72. argument shall not point to the pathname of a directory. If the link
  73. named by the
  74. .IR new
  75. argument exists, it shall be removed and
  76. .IR old
  77. renamed to
  78. .IR new .
  79. In this case, a link named
  80. .IR new
  81. shall remain visible to other threads throughout the renaming operation
  82. and refer either to the file referred to by
  83. .IR new
  84. or
  85. .IR old
  86. before the operation began. Write access permission is required for
  87. both the directory containing
  88. .IR old
  89. and the directory containing
  90. .IR new .
  91. .P
  92. If the
  93. .IR old
  94. argument points to the pathname of a directory, the
  95. .IR new
  96. argument shall not point to the pathname of a file that is not a
  97. directory. If the directory named by the
  98. .IR new
  99. argument exists, it shall be removed and
  100. .IR old
  101. renamed to
  102. .IR new .
  103. In this case, a link named
  104. .IR new
  105. shall exist throughout the renaming operation and shall refer either to
  106. the directory referred to by
  107. .IR new
  108. or
  109. .IR old
  110. before the operation began. If
  111. .IR new
  112. names an existing directory, it shall be required to be an empty
  113. directory.
  114. .P
  115. If either
  116. .IR pathname
  117. argument refers to a path whose final component is either dot or
  118. dot-dot,
  119. \fIrename\fR()
  120. shall fail.
  121. .P
  122. If the
  123. .IR old
  124. argument points to a pathname of a symbolic link, the symbolic link
  125. shall be renamed. If the
  126. .IR new
  127. argument points to a pathname of a symbolic link, the symbolic link
  128. shall be removed.
  129. .P
  130. The
  131. .IR old
  132. pathname shall not name an ancestor directory of the
  133. .IR new
  134. pathname. Write access permission is required for the directory containing
  135. .IR old
  136. and the directory containing
  137. .IR new .
  138. If the
  139. .IR old
  140. argument points to the pathname of a directory, write access permission
  141. may be required for the directory named by
  142. .IR old ,
  143. and, if it exists, the directory named by
  144. .IR new .
  145. .P
  146. If the link named by the
  147. .IR new
  148. argument exists and the file's link count becomes 0 when it is removed
  149. and no process has the file open, the space occupied by the file shall
  150. be freed and the file shall no longer be accessible. If one or more
  151. processes have the file open when the last link is removed, the link
  152. shall be removed before
  153. \fIrename\fR()
  154. returns, but the removal of the file contents shall be postponed until
  155. all references to the file are closed.
  156. .P
  157. Upon successful completion,
  158. \fIrename\fR()
  159. shall mark for update the last data modification and last file status
  160. change timestamps of the parent directory of each file.
  161. .P
  162. If the
  163. \fIrename\fR()
  164. function fails for any reason other than
  165. .BR [EIO] ,
  166. any file named by
  167. .IR new
  168. shall be unaffected.
  169. .P
  170. The
  171. \fIrenameat\fR()
  172. function shall be equivalent to the
  173. \fIrename\fR()
  174. function except in the case where either
  175. .IR old
  176. or
  177. .IR new
  178. specifies a relative path. If
  179. .IR old
  180. is a relative path, the file to be renamed is located relative to the
  181. directory associated with the file descriptor
  182. .IR oldfd
  183. instead of the current working directory. If
  184. .IR new
  185. is a relative path, the same happens only relative to the directory
  186. associated with
  187. .IR newfd .
  188. If the access mode of the open file description associated with the
  189. file descriptor is not O_SEARCH, the function shall check whether
  190. directory searches are permitted using the current permissions of
  191. the directory underlying the file descriptor. If the access mode is
  192. O_SEARCH, the function shall not perform the check.
  193. .P
  194. If
  195. \fIrenameat\fR()
  196. is passed the special value AT_FDCWD in the
  197. .IR oldfd
  198. or
  199. .IR newfd
  200. parameter, the current working directory shall be used in the
  201. determination of the file for the respective
  202. .IR path
  203. parameter.
  204. .SH "RETURN VALUE"
  205. Upon successful completion, the
  206. \fIrename\fR()
  207. function shall return 0. Otherwise, it shall return \-1,
  208. .IR errno
  209. shall be set to indicate the error,
  210. and neither the file named by
  211. .IR old
  212. nor the file named by
  213. .IR new
  214. shall be changed or created.
  215. .P
  216. Upon successful completion, the
  217. \fIrenameat\fR()
  218. function shall return 0. Otherwise, it shall return \-1 and set
  219. .IR errno
  220. to indicate the error.
  221. .SH ERRORS
  222. The
  223. \fIrename\fR()
  224. and
  225. \fIrenameat\fR()
  226. functions shall fail if:
  227. .TP
  228. .BR EACCES
  229. A component of either path prefix denies search permission; or one of
  230. the directories containing
  231. .IR old
  232. or
  233. .IR new
  234. denies write permissions; or, write permission is required and is
  235. denied for a directory pointed to by the
  236. .IR old
  237. or
  238. .IR new
  239. arguments.
  240. .TP
  241. .BR EBUSY
  242. The directory named by
  243. .IR old
  244. or
  245. .IR new
  246. is currently in use by the system or another process, and the
  247. implementation considers this an error.
  248. .IP "[EEXIST]\ or\ [ENOTEMPTY]" 12
  249. .br
  250. The link named by
  251. .IR new
  252. is a directory that is not an empty directory.
  253. .TP
  254. .BR EINVAL
  255. The
  256. .IR old
  257. pathname names an ancestor directory of the
  258. .IR new
  259. pathname, or either pathname argument contains a final component that
  260. is dot or dot-dot.
  261. .TP
  262. .BR EIO
  263. A physical I/O error has occurred.
  264. .TP
  265. .BR EISDIR
  266. The
  267. .IR new
  268. argument points to a directory and the
  269. .IR old
  270. argument points to a file that is not a directory.
  271. .TP
  272. .BR ELOOP
  273. A loop exists in symbolic links encountered during resolution of the
  274. .IR path
  275. argument.
  276. .TP
  277. .BR EMLINK
  278. The file named by
  279. .IR old
  280. is a directory, and the link count of the parent directory of
  281. .IR new
  282. would exceed
  283. {LINK_MAX}.
  284. .TP
  285. .BR ENAMETOOLONG
  286. .br
  287. The length of a component of a pathname is longer than
  288. {NAME_MAX}.
  289. .TP
  290. .BR ENOENT
  291. The link named by
  292. .IR old
  293. does not name an existing file, a component of the path prefix of
  294. .IR new
  295. does not exist, or either
  296. .IR old
  297. or
  298. .IR new
  299. points to an empty string.
  300. .TP
  301. .BR ENOSPC
  302. The directory that would contain
  303. .IR new
  304. cannot be extended.
  305. .TP
  306. .BR ENOTDIR
  307. A component of either path prefix names an existing file that is
  308. neither a directory nor a symbolic link to a directory; or the
  309. .IR old
  310. argument names a directory and the
  311. .IR new
  312. argument names a non-directory file; or the
  313. .IR old
  314. argument contains at least one non-\c
  315. <slash>
  316. character and ends with one or more trailing
  317. <slash>
  318. characters and the last pathname component names an existing file that
  319. is neither a directory nor a symbolic link to a directory; or the
  320. .IR old
  321. argument names an existing non-directory file and the
  322. .IR new
  323. argument names a nonexistent file, contains at least one non-\c
  324. <slash>
  325. character, and ends with one or more trailing
  326. <slash>
  327. characters; or the
  328. .IR new
  329. argument names an existing non-directory file, contains at least one non-\c
  330. <slash>
  331. character, and ends with one or more trailing
  332. <slash>
  333. characters.
  334. .TP
  335. .BR EPERM " or " EACCES
  336. .br
  337. The S_ISVTX flag is set on the directory containing the file referred
  338. to by
  339. .IR old
  340. and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2017,
  341. .IR "Section 4.3" ", " "Directory Protection"
  342. with respect to
  343. .IR old ;
  344. or
  345. .IR new
  346. refers to an existing file, the S_ISVTX flag is set on the directory
  347. containing this file, and the process does not satisfy the criteria
  348. specified in the Base Definitions volume of POSIX.1\(hy2017,
  349. .IR "Section 4.3" ", " "Directory Protection"
  350. with respect to this file.
  351. .TP
  352. .BR EROFS
  353. The requested operation requires writing in a directory on a read-only
  354. file system.
  355. .TP
  356. .BR EXDEV
  357. The links named by
  358. .IR new
  359. and
  360. .IR old
  361. are on different file systems and the implementation does not support
  362. links between file systems.
  363. .P
  364. In addition, the
  365. \fIrenameat\fR()
  366. function shall fail if:
  367. .TP
  368. .BR EACCES
  369. The access mode of the open file description associated with
  370. .IR oldfd
  371. or
  372. .IR newfd
  373. is not O_SEARCH and the permissions of the directory underlying
  374. .IR oldfd
  375. or
  376. .IR newfd ,
  377. respectively, do not permit directory searches.
  378. .TP
  379. .BR EBADF
  380. The
  381. .IR old
  382. argument does not specify an absolute path and the
  383. .IR oldfd
  384. argument is neither AT_FDCWD nor a valid file descriptor open for
  385. reading or searching, or the
  386. .IR new
  387. argument does not specify an absolute path and the
  388. .IR newfd
  389. argument is neither AT_FDCWD nor a valid file descriptor open
  390. for reading or searching.
  391. .TP
  392. .BR ENOTDIR
  393. The
  394. .IR old
  395. or
  396. .IR new
  397. argument is not an absolute path and
  398. .IR oldfd
  399. or
  400. .IR newfd ,
  401. respectively, is a file descriptor associated with a non-directory file.
  402. .P
  403. The
  404. \fIrename\fR()
  405. and
  406. \fIrenameat\fR()
  407. functions may fail if:
  408. .TP
  409. .BR EBUSY
  410. The file named by the
  411. .IR old
  412. or
  413. .IR new
  414. arguments is a named STREAM.
  415. .TP
  416. .BR ELOOP
  417. More than
  418. {SYMLOOP_MAX}
  419. symbolic links were encountered during resolution of the
  420. .IR path
  421. argument.
  422. .TP
  423. .BR ENAMETOOLONG
  424. .br
  425. The length of a pathname exceeds
  426. {PATH_MAX},
  427. or pathname resolution of a symbolic link produced an intermediate
  428. result with a length that exceeds
  429. {PATH_MAX}.
  430. .TP
  431. .BR ETXTBSY
  432. The file named by
  433. .IR new
  434. exists and is the last directory entry to a pure procedure (shared text)
  435. file that is being executed.
  436. .LP
  437. .IR "The following sections are informative."
  438. .SH EXAMPLES
  439. .SS "Renaming a File"
  440. .P
  441. The following example shows how to rename a file named
  442. .BR /home/cnd/mod1
  443. to
  444. .BR /home/cnd/mod2 .
  445. .sp
  446. .RS 4
  447. .nf
  448. #include <stdio.h>
  449. .P
  450. int status;
  451. \&...
  452. status = rename("/home/cnd/mod1", "/home/cnd/mod2");
  453. .fi
  454. .P
  455. .RE
  456. .SH "APPLICATION USAGE"
  457. Some implementations mark for update the last file status change timestamp
  458. of renamed files and some do not. Applications which make use of the
  459. last file status change timestamp may behave differently with respect
  460. to renamed files unless they are designed to allow for either behavior.
  461. .SH RATIONALE
  462. This
  463. \fIrename\fR()
  464. function is equivalent for regular files to that defined by the ISO\ C standard.
  465. Its inclusion here expands that definition to include actions on
  466. directories and specifies behavior when the
  467. .IR new
  468. parameter names a file that already exists. That specification
  469. requires that the action of the function be atomic.
  470. .P
  471. One of the reasons for introducing this function was to have a means of
  472. renaming directories while permitting implementations to prohibit the
  473. use of
  474. \fIlink\fR()
  475. and
  476. \fIunlink\fR()
  477. with directories, thus constraining links to directories to those made by
  478. \fImkdir\fR().
  479. .P
  480. The specification that if
  481. .IR old
  482. and
  483. .IR new
  484. refer to the same file is intended to guarantee that:
  485. .sp
  486. .RS 4
  487. .nf
  488. rename("x", "x");
  489. .fi
  490. .P
  491. .RE
  492. .P
  493. does not remove the file.
  494. .P
  495. Renaming dot or dot-dot is prohibited in order to prevent cyclical file
  496. system paths.
  497. .P
  498. See also the descriptions of
  499. .BR [ENOTEMPTY]
  500. and
  501. .BR [ENAMETOOLONG]
  502. in
  503. \fIrmdir\fR()
  504. and
  505. .BR [EBUSY]
  506. in
  507. \fIunlink\fR().
  508. For a discussion of
  509. .BR [EXDEV] ,
  510. see
  511. \fIlink\fR().
  512. .P
  513. The purpose of the
  514. \fIrenameat\fR()
  515. function is to rename files in directories other than the current
  516. working directory without exposure to race conditions. Any part of the
  517. path of a file could be changed in parallel to a call to
  518. \fIrename\fR(),
  519. resulting in unspecified behavior. By opening file descriptors for the
  520. source and target directories and using the
  521. \fIrenameat\fR()
  522. function it can be guaranteed that that renamed file is located correctly
  523. and the resulting file is in the desired directory.
  524. .SH "FUTURE DIRECTIONS"
  525. None.
  526. .SH "SEE ALSO"
  527. .IR "\fIlink\fR\^(\|)",
  528. .IR "\fIrmdir\fR\^(\|)",
  529. .IR "\fIsymlink\fR\^(\|)",
  530. .IR "\fIunlink\fR\^(\|)"
  531. .P
  532. The Base Definitions volume of POSIX.1\(hy2017,
  533. .IR "Section 4.3" ", " "Directory Protection",
  534. .IR "\fB<fcntl.h>\fP",
  535. .IR "\fB<stdio.h>\fP"
  536. .\"
  537. .SH COPYRIGHT
  538. Portions of this text are reprinted and reproduced in electronic form
  539. from IEEE Std 1003.1-2017, Standard for Information Technology
  540. -- Portable Operating System Interface (POSIX), The Open Group Base
  541. Specifications Issue 7, 2018 Edition,
  542. Copyright (C) 2018 by the Institute of
  543. Electrical and Electronics Engineers, Inc and The Open Group.
  544. In the event of any discrepancy between this version and the original IEEE and
  545. The Open Group Standard, the original IEEE and The Open Group Standard
  546. is the referee document. The original Standard can be obtained online at
  547. http://www.opengroup.org/unix/online.html .
  548. .PP
  549. Any typographical or formatting errors that appear
  550. in this page are most likely
  551. to have been introduced during the conversion of the source files to
  552. man page format. To report such errors, see
  553. https://www.kernel.org/doc/man-pages/reporting_bugs.html .