]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
ac56b6a8 | 2 | .\" and Copyright (C) 1993 Michael Haardt; |
9cab982f MK |
3 | .\" and Copyright (C) 1993,1995 Ian Jackson |
4 | .\" and Copyright (C) 2006, 2014 Michael Kerrisk | |
fea681da | 5 | .\" |
93015253 | 6 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
7 | .\" Permission is granted to make and distribute verbatim copies of this |
8 | .\" manual provided the copyright notice and this permission notice are | |
9 | .\" preserved on all copies. | |
10 | .\" | |
11 | .\" Permission is granted to copy and distribute modified versions of this | |
12 | .\" manual under the conditions for verbatim copying, provided that the | |
13 | .\" entire resulting derived work is distributed under the terms of a | |
14 | .\" permission notice identical to this one. | |
c13182ef | 15 | .\" |
fea681da MK |
16 | .\" Since the Linux kernel and libraries are constantly changing, this |
17 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
18 | .\" responsibility for errors or omissions, or for damages resulting from | |
19 | .\" the use of the information contained herein. The author(s) may not | |
20 | .\" have taken the same level of care in the production of this manual, | |
21 | .\" which is licensed free of charge, as they might when working | |
22 | .\" professionally. | |
c13182ef | 23 | .\" |
fea681da MK |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 26 | .\" %%%LICENSE_END |
fea681da MK |
27 | .\" |
28 | .\" Modified Sat Jul 24 00:35:52 1993 by Rik Faith <faith@cs.unc.edu> | |
29 | .\" Modified Thu Jun 4 12:21:13 1998 by Andries Brouwer <aeb@cwi.nl> | |
2d5d4b0d | 30 | .\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt <michael@moria.de> |
f6a4055f | 31 | .\" 2007-03-25, mtk, added various text to DESCRIPTION. |
fea681da | 32 | .\" |
5722c835 | 33 | .TH RENAME 2 2015-07-23 "Linux" "Linux Programmer's Manual" |
fea681da | 34 | .SH NAME |
ab99efdd | 35 | rename, renameat, renameat2 \- change the name or location of a file |
fea681da | 36 | .SH SYNOPSIS |
9cab982f | 37 | .nf |
fea681da MK |
38 | .B #include <stdio.h> |
39 | .sp | |
40 | .BI "int rename(const char *" oldpath ", const char *" newpath ); | |
9cab982f MK |
41 | .sp |
42 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" | |
43 | .B #include <stdio.h> | |
44 | .sp | |
45 | .BI "int renameat(int " olddirfd ", const char *" oldpath , | |
46 | .BI " int " newdirfd ", const char *" newpath ); | |
ab99efdd MS |
47 | |
48 | .BI "int renameat2(int " olddirfd ", const char *" oldpath , | |
84f573db MK |
49 | .BI " int " newdirfd ", const char *" newpath \ |
50 | ", unsigned int " flags ); | |
9cab982f MK |
51 | .fi |
52 | .sp | |
53 | .in -4n | |
54 | Feature Test Macro Requirements for glibc (see | |
55 | .BR feature_test_macros (7)): | |
56 | .in | |
57 | .sp | |
58 | .BR renameat (): | |
59 | .PD 0 | |
60 | .ad l | |
61 | .RS 4 | |
62 | .TP 4 | |
63 | Since glibc 2.10: | |
64 | _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L | |
65 | .TP | |
66 | Before glibc 2.10: | |
67 | _ATFILE_SOURCE | |
bea08fec | 68 | .\" FIXME . need to define FTMs for renameat2(), once it hits glibc |
9cab982f MK |
69 | .RE |
70 | .ad | |
71 | .PD | |
fea681da | 72 | .SH DESCRIPTION |
e511ffb6 | 73 | .BR rename () |
fea681da | 74 | renames a file, moving it between directories if required. |
fea681da MK |
75 | Any other hard links to the file (as created using |
76 | .BR link (2)) | |
77 | are unaffected. | |
f6a4055f MK |
78 | Open file descriptors for |
79 | .I oldpath | |
80 | are also unaffected. | |
fea681da MK |
81 | |
82 | If | |
83 | .I newpath | |
afb3d50c | 84 | already exists, it will be atomically replaced (subject to |
e9496f74 | 85 | a few conditions; see ERRORS below), so that there is |
fea681da MK |
86 | no point at which another process attempting to access |
87 | .I newpath | |
88 | will find it missing. | |
89 | ||
f6a4055f MK |
90 | If |
91 | .I oldpath | |
92 | and | |
93 | .I newpath | |
94 | are existing hard links referring to the same file, then | |
95 | .BR rename () | |
96 | does nothing, and returns a success status. | |
97 | ||
fea681da MK |
98 | If |
99 | .I newpath | |
afb3d50c | 100 | exists but the operation fails for some reason, |
e511ffb6 | 101 | .BR rename () |
fea681da MK |
102 | guarantees to leave an instance of |
103 | .I newpath | |
104 | in place. | |
105 | ||
f6a4055f MK |
106 | .I oldpath |
107 | can specify a directory. | |
c13182ef | 108 | In this case, |
f6a4055f MK |
109 | .I newpath |
110 | must either not exist, or it must specify an empty directory. | |
111 | ||
fea681da MK |
112 | However, when overwriting there will probably be a window in which |
113 | both | |
114 | .I oldpath | |
115 | and | |
116 | .I newpath | |
117 | refer to the file being renamed. | |
118 | ||
119 | If | |
120 | .I oldpath | |
afb3d50c | 121 | refers to a symbolic link, the link is renamed; if |
fea681da | 122 | .I newpath |
afb3d50c | 123 | refers to a symbolic link, the link will be overwritten. |
0ce8e1cd | 124 | .SS renameat() |
9cab982f MK |
125 | The |
126 | .BR renameat () | |
127 | system call operates in exactly the same way as | |
cadd38ba | 128 | .BR rename (), |
9cab982f MK |
129 | except for the differences described here. |
130 | ||
131 | If the pathname given in | |
132 | .I oldpath | |
133 | is relative, then it is interpreted relative to the directory | |
134 | referred to by the file descriptor | |
135 | .I olddirfd | |
136 | (rather than relative to the current working directory of | |
137 | the calling process, as is done by | |
cadd38ba | 138 | .BR rename () |
9cab982f MK |
139 | for a relative pathname). |
140 | ||
141 | If | |
142 | .I oldpath | |
143 | is relative and | |
144 | .I olddirfd | |
145 | is the special value | |
146 | .BR AT_FDCWD , | |
147 | then | |
148 | .I oldpath | |
149 | is interpreted relative to the current working | |
150 | directory of the calling process (like | |
cadd38ba | 151 | .BR rename ()). |
9cab982f MK |
152 | |
153 | If | |
154 | .I oldpath | |
155 | is absolute, then | |
156 | .I olddirfd | |
157 | is ignored. | |
158 | ||
159 | The interpretation of | |
160 | .I newpath | |
161 | is as for | |
162 | .IR oldpath , | |
163 | except that a relative pathname is interpreted relative | |
164 | to the directory referred to by the file descriptor | |
165 | .IR newdirfd . | |
166 | ||
167 | See | |
168 | .BR openat (2) | |
169 | for an explanation of the need for | |
170 | .BR renameat (). | |
ab99efdd MS |
171 | .SS renameat2() |
172 | .BR renameat2 () | |
173 | has an additional | |
174 | .I flags | |
175 | argument. | |
176 | A | |
177 | .BR renameat2 () | |
178 | call with a zero | |
179 | .I flags | |
180 | argument is equivalent to | |
181 | .BR renameat (). | |
182 | ||
183 | The | |
184 | .I flags | |
185 | argument is a bit mask consisting of zero or more of the following flags: | |
186 | .TP | |
ab99efdd MS |
187 | .B RENAME_EXCHANGE |
188 | Atomically exchange | |
189 | .IR oldpath | |
190 | and | |
191 | .IR newpath . | |
192 | Both pathnames must exist | |
193 | but may be of different types (e.g., one could be a non-empty directory | |
194 | and the other a symbolic link). | |
c9c7821b MK |
195 | .TP |
196 | .B RENAME_NOREPLACE | |
197 | Don't overwrite | |
198 | .IR newpath | |
199 | of the rename. | |
200 | Return an error if | |
201 | .IR newpath | |
202 | already exists. | |
d35b5dd3 MK |
203 | |
204 | .B RENAME_NOREPLACE | |
205 | can't be employed together with | |
206 | .BR RENAME_EXCHANGE . | |
0ebe7b93 MK |
207 | .TP |
208 | .BR RENAME_WHITEOUT " (since Linux 3.18)" | |
209 | .\" commit 0d7a855526dd672e114aff2ac22b60fc6f155b08 | |
86dbf1bb | 210 | .\" commit 787fb6bc9682ec7c05fb5d9561b57100fbc1cc41 |
0ebe7b93 MK |
211 | This operation makes sense only for overlay/union |
212 | filesystem implementations. | |
213 | ||
214 | Specifying | |
215 | .B RENAME_WHITEOUT | |
216 | creates a "whiteout" object at the source of | |
217 | the rename at the same time as performing the rename. | |
218 | The whole operation is atomic, | |
219 | so that if the rename succeeds then the whiteout will also have been created. | |
220 | ||
221 | A "whiteout" is an object that has special meaning in union/overlay | |
222 | filesystem constructs. | |
223 | In these constructs, | |
224 | multiple layers exist and only the top one is ever modified. | |
225 | A whiteout on an upper layer will effectively hide a | |
226 | matching file in the lower layer, | |
227 | making it appear as if the file didn't exist. | |
228 | ||
229 | When a file that exists on the lower layer is renamed, | |
230 | the file is first copied up (if not already on the upper layer) | |
8cc4d071 | 231 | and then renamed on the upper, read-write layer. |
0ebe7b93 MK |
232 | At the same time, the source file needs to be "whiteouted" |
233 | (so that the version of the source file in the lower layer | |
234 | is rendered invisible). | |
235 | The whole operation needs to be done atomically. | |
236 | ||
237 | When not part of a union/overlay, | |
238 | the whiteout appears as a character device with a {0,0} device number. | |
239 | ||
240 | .B RENAME_WHITEOUT | |
241 | requires the same privileges as creating a device node (i.e., the | |
242 | .BR CAP_MKNOD | |
243 | capability). | |
244 | ||
245 | .B RENAME_WHITEOUT | |
246 | can't be employed together with | |
247 | .BR RENAME_EXCHANGE . | |
248 | ||
249 | .B RENAME_WHITEOUT | |
250 | requires support from the underlying filesystem. | |
251 | Among the filesystems that provide that support are | |
252 | shmem (since Linux 3.18), | |
253 | .\" shmem: commit 46fdb794e3f52ef18b859ebc92f0a9d7db21c5df | |
254 | ext4 (since Linux 3.18), | |
255 | .\" ext4: commit cd808deced431b66b5fa4e5c193cb7ec0059eaff | |
256 | and XFS (since Linux 4.1). | |
257 | .\" XFS: commit 7dcf5c3e4527cfa2807567b00387cf2ed5e07f00 | |
47297adb | 258 | .SH RETURN VALUE |
c13182ef MK |
259 | On success, zero is returned. |
260 | On error, \-1 is returned, and | |
fea681da MK |
261 | .I errno |
262 | is set appropriately. | |
263 | .SH ERRORS | |
264 | .TP | |
265 | .B EACCES | |
266 | Write permission is denied for the directory containing | |
267 | .I oldpath | |
268 | or | |
269 | .IR newpath , | |
270 | or, search permission is denied for one of the directories | |
271 | in the path prefix of | |
272 | .I oldpath | |
273 | or | |
274 | .IR newpath , | |
275 | or | |
276 | .I oldpath | |
277 | is a directory and does not allow write permission (needed to update | |
278 | the | |
836f07c1 | 279 | .I .. |
fea681da MK |
280 | entry). |
281 | (See also | |
ad7cc990 | 282 | .BR path_resolution (7).) |
fea681da MK |
283 | .TP |
284 | .B EBUSY | |
285 | The rename fails because | |
286 | .IR oldpath " or " newpath | |
287 | is a directory that is in use by some process (perhaps as | |
288 | current working directory, or as root directory, or because | |
289 | it was open for reading) or is in use by the system | |
290 | (for example as mount point), while the system considers | |
291 | this an error. | |
682edefb | 292 | (Note that there is no requirement to return |
0daa9e92 | 293 | .B EBUSY |
682edefb | 294 | in such |
5503c85e MK |
295 | cases\(emthere is nothing wrong with doing the rename anyway\(embut |
296 | it is allowed to return | |
682edefb MK |
297 | .B EBUSY |
298 | if the system cannot otherwise | |
fea681da MK |
299 | handle such situations.) |
300 | .TP | |
a1f01685 | 301 | .B EDQUOT |
9ee4a2b6 | 302 | The user's quota of disk blocks on the filesystem has been exhausted. |
a1f01685 | 303 | .TP |
fea681da MK |
304 | .B EFAULT |
305 | .IR oldpath " or " newpath " points outside your accessible address space." | |
306 | .TP | |
307 | .B EINVAL | |
308 | The new pathname contained a path prefix of the old, or, more generally, | |
309 | an attempt was made to make a directory a subdirectory of itself. | |
310 | .TP | |
311 | .B EISDIR | |
312 | .I newpath | |
313 | is an existing directory, but | |
314 | .I oldpath | |
315 | is not a directory. | |
316 | .TP | |
317 | .B ELOOP | |
318 | Too many symbolic links were encountered in resolving | |
319 | .IR oldpath " or " newpath . | |
320 | .TP | |
321 | .B EMLINK | |
322 | .I oldpath | |
323 | already has the maximum number of links to it, or | |
324 | it was a directory and the directory containing | |
325 | .I newpath | |
326 | has the maximum number of links. | |
327 | .TP | |
328 | .B ENAMETOOLONG | |
329 | .IR oldpath " or " newpath " was too long." | |
330 | .TP | |
331 | .B ENOENT | |
3d81b967 MK |
332 | The link named by |
333 | .I oldpath | |
334 | does not exist; | |
335 | or, a directory component in | |
336 | .I newpath | |
337 | does not exist; | |
338 | or, | |
339 | .I oldpath | |
340 | or | |
341 | .I newpath | |
342 | is an empty string. | |
fea681da MK |
343 | .TP |
344 | .B ENOMEM | |
345 | Insufficient kernel memory was available. | |
346 | .TP | |
347 | .B ENOSPC | |
348 | The device containing the file has no room for the new directory | |
349 | entry. | |
350 | .TP | |
351 | .B ENOTDIR | |
352 | A component used as a directory in | |
353 | .IR oldpath " or " newpath | |
354 | is not, in fact, a directory. | |
355 | Or, | |
356 | .I oldpath | |
357 | is a directory, and | |
358 | .I newpath | |
359 | exists but is not a directory. | |
360 | .TP | |
361 | .BR ENOTEMPTY " or " EEXIST | |
0daa9e92 | 362 | .I newpath |
aa796481 | 363 | is a nonempty directory, that is, contains entries other than "." and "..". |
fea681da MK |
364 | .TP |
365 | .BR EPERM " or " EACCES | |
366 | The directory containing | |
367 | .I oldpath | |
368 | has the sticky bit | |
369 | .RB ( S_ISVTX ) | |
370 | set and the process's effective user ID is neither | |
371 | the user ID of the file to be deleted nor that of the directory | |
372 | containing it, and the process is not privileged | |
373 | (Linux: does not have the | |
374 | .B CAP_FOWNER | |
375 | capability); | |
376 | or | |
377 | .I newpath | |
378 | is an existing file and the directory containing it has the sticky bit set | |
379 | and the process's effective user ID is neither the user ID of the file | |
380 | to be replaced nor that of the directory containing it, | |
381 | and the process is not privileged | |
382 | (Linux: does not have the | |
383 | .B CAP_FOWNER | |
384 | capability); | |
9ee4a2b6 | 385 | or the filesystem containing |
0daa9e92 | 386 | .I pathname |
fea681da MK |
387 | does not support renaming of the type requested. |
388 | .TP | |
389 | .B EROFS | |
9ee4a2b6 | 390 | The file is on a read-only filesystem. |
fea681da MK |
391 | .TP |
392 | .B EXDEV | |
393 | .IR oldpath " and " newpath | |
9ee4a2b6 MK |
394 | are not on the same mounted filesystem. |
395 | (Linux permits a filesystem to be mounted at multiple points, but | |
2777b1ca | 396 | .BR rename () |
2d5d4b0d | 397 | does not work across different mount points, |
9ee4a2b6 | 398 | even if the same filesystem is mounted on both.) |
9cab982f MK |
399 | .PP |
400 | The following additional errors can occur for | |
ab99efdd MS |
401 | .BR renameat () |
402 | and | |
403 | .BR renameat2 (): | |
9cab982f MK |
404 | .TP |
405 | .B EBADF | |
406 | .I olddirfd | |
407 | or | |
408 | .I newdirfd | |
409 | is not a valid file descriptor. | |
410 | .TP | |
411 | .B ENOTDIR | |
412 | .I oldpath | |
413 | is relative and | |
414 | .I olddirfd | |
415 | is a file descriptor referring to a file other than a directory; | |
416 | or similar for | |
417 | .I newpath | |
418 | and | |
419 | .I newdirfd | |
ab99efdd MS |
420 | .PP |
421 | The following additional errors can occur for | |
422 | .BR renameat2 (): | |
423 | .TP | |
424 | .B EEXIST | |
425 | .I flags | |
426 | contains | |
427 | .B RENAME_NOREPLACE | |
428 | and | |
429 | .I newpath | |
430 | already exists. | |
ffb30e75 | 431 | .TP |
ab99efdd | 432 | .B EINVAL |
5c1517fa | 433 | An invalid flag was specified in |
de332fe8 MK |
434 | .IR flags . |
435 | .TP | |
436 | .B EINVAL | |
437 | Both | |
5c1517fa MK |
438 | .B RENAME_NOREPLACE |
439 | and | |
440 | .B RENAME_EXCHANGE | |
de332fe8 MK |
441 | were specified in |
442 | .IR flags . | |
ab99efdd MS |
443 | .TP |
444 | .B EINVAL | |
0ebe7b93 MK |
445 | Both |
446 | .B RENAME_WHITEOUT | |
447 | and | |
448 | .B RENAME_EXCHANGE | |
449 | were specified in | |
450 | .IR flags . | |
451 | .TP | |
452 | .B EINVAL | |
ab99efdd MS |
453 | The filesystem does not support one of the flags in |
454 | .IR flags . | |
455 | .TP | |
456 | .B ENOENT | |
457 | .I flags | |
8f60952e | 458 | contains |
ab99efdd | 459 | .B RENAME_EXCHANGE |
8f60952e MK |
460 | and |
461 | .IR newpath | |
462 | does not exist. | |
0ebe7b93 MK |
463 | .TP |
464 | .B EPERM | |
465 | .B RENAME_WHITEOUT | |
466 | was specified in | |
467 | .IR flags , | |
468 | but the caller does not have the | |
469 | .B CAP_MKNOD | |
470 | capability. | |
9cab982f MK |
471 | .SH VERSIONS |
472 | .BR renameat () | |
473 | was added to Linux in kernel 2.6.16; | |
474 | library support was added to glibc in version 2.4. | |
4e6c4ab2 MK |
475 | |
476 | .BR renameat2 () | |
477 | was added to Linux in kernel 3.15. | |
bea08fec | 478 | .\" FIXME . glibc support is pending. |
47297adb | 479 | .SH CONFORMING TO |
9cab982f | 480 | .BR rename (): |
1e8473f4 | 481 | 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008. |
9cab982f MK |
482 | |
483 | .BR renameat (): | |
484 | POSIX.1-2008. | |
4e6c4ab2 | 485 | |
0ce8e1cd | 486 | .BR renameat2 () |
4e6c4ab2 | 487 | is Linux-specific. |
387ebb9c MK |
488 | .SH NOTES |
489 | .SS Glibc notes | |
490 | On older kernels where | |
491 | .BR renameat () | |
492 | is unavailable, the glibc wrapper function falls back to the use of | |
493 | .BR rename (). | |
494 | When | |
495 | .I oldpath | |
496 | and | |
497 | .I newpath | |
498 | are relative pathnames, | |
499 | glibc constructs pathnames based on the symbolic links in | |
500 | .IR /proc/self/fd | |
501 | that correspond to the | |
502 | .I olddirfd | |
503 | and | |
504 | .IR newdirfd | |
505 | arguments. | |
fea681da | 506 | .SH BUGS |
9ee4a2b6 | 507 | On NFS filesystems, you can not assume that if the operation |
afb3d50c | 508 | failed, the file was not renamed. |
c13182ef | 509 | If the server does the rename operation |
fea681da | 510 | and then crashes, the retransmitted RPC which will be processed when the |
c13182ef MK |
511 | server is up again causes a failure. |
512 | The application is expected to | |
513 | deal with this. | |
514 | See | |
fea681da MK |
515 | .BR link (2) |
516 | for a similar problem. | |
47297adb | 517 | .SH SEE ALSO |
fea681da MK |
518 | .BR mv (1), |
519 | .BR chmod (2), | |
520 | .BR link (2), | |
fea681da | 521 | .BR symlink (2), |
ad7cc990 | 522 | .BR unlink (2), |
a9cfde1d | 523 | .BR path_resolution (7), |
ad22ad55 | 524 | .BR symlink (7) |