Debian Codegraph @

upstream/debian-unstable/man2/rename.2

raw
1 .\" Copyright 1992, Drew Eckhardt <[email protected]>
2 .\" Copyright 1993-1995, Ian Jackson <[email protected]>
3 .\" Copyright 2006-2014, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH rename 2 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 rename, renameat, renameat2 \- change the name or location of a file
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdio.h>
17 .P
18 .BI "int rename(const char *" oldpath ", const char *" newpath );
19 .P
20 .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
21 .B #include <stdio.h>
22 .P
23 .BI "int renameat(int " olddirfd ", const char *" oldpath ,
24 .BI " int " newdirfd ", const char *" newpath );
25 .BI "int renameat2(int " olddirfd ", const char *" oldpath ,
26 .BI " int " newdirfd ", const char *" newpath \
27 ", unsigned int " flags );
28 .fi
29 .P
30 .RS -4
31 Feature Test Macro Requirements for glibc (see
32 .BR feature_test_macros (7)):
33 .RE
34 .P
35 .nf
36 .BR renameat ():
37 Since glibc 2.10:
38 _POSIX_C_SOURCE >= 200809L
39 Before glibc 2.10:
40 _ATFILE_SOURCE
41 .P
42 .BR renameat2 ():
43 _GNU_SOURCE
44 .fi
45 .SH DESCRIPTION
46 .BR rename ()
47 renames a file, moving it between directories if required.
48 Any other hard links to the file (as created using
49 .BR link (2))
50 are unaffected.
51 Open file descriptors for
52 .I oldpath
53 are also unaffected.
54 .P
55 Various restrictions determine whether or not the rename operation succeeds:
56 see ERRORS below.
57 .P
58 If
59 .I newpath
60 already exists, it will be atomically replaced, so that there is
61 no point at which another process attempting to access
62 .I newpath
63 will find it missing.
64 However, there will probably be a window in which both
65 .I oldpath
66 and
67 .I newpath
68 refer to the file being renamed.
69 .P
70 If
71 .I oldpath
72 and
73 .I newpath
74 are existing hard links referring to the same file, then
75 .BR rename ()
76 does nothing, and returns a success status.
77 .P
78 If
79 .I newpath
80 exists but the operation fails for some reason,
81 .BR rename ()
82 guarantees to leave an instance of
83 .I newpath
84 in place.
85 .P
86 .I oldpath
87 can specify a directory.
88 In this case,
89 .I newpath
90 must either not exist, or it must specify an empty directory.
91 .P
92 If
93 .I oldpath
94 refers to a symbolic link, the link is renamed;
95 if
96 .I newpath
97 refers to a symbolic link, the link will be overwritten.
98 .SS renameat()
99 The
100 .BR renameat ()
101 system call operates in exactly the same way as
102 .BR rename (),
103 except for the differences described here.
104 .P
105 If the pathname given in
106 .I oldpath
107 is relative, then it is interpreted relative to the directory
108 referred to by the file descriptor
109 .I olddirfd
110 (rather than relative to the current working directory of
111 the calling process, as is done by
112 .BR rename ()
113 for a relative pathname).
114 .P
115 If
116 .I oldpath
117 is relative and
118 .I olddirfd
119 is the special value
120 .BR AT_FDCWD ,
121 then
122 .I oldpath
123 is interpreted relative to the current working
124 directory of the calling process (like
125 .BR rename ()).
126 .P
127 If
128 .I oldpath
129 is absolute, then
130 .I olddirfd
131 is ignored.
132 .P
133 The interpretation of
134 .I newpath
135 is as for
136 .IR oldpath ,
137 except that a relative pathname is interpreted relative
138 to the directory referred to by the file descriptor
139 .IR newdirfd .
140 .P
141 See
142 .BR openat (2)
143 for an explanation of the need for
144 .BR renameat ().
145 .SS renameat2()
146 .BR renameat2 ()
147 has an additional
148 .I flags
149 argument.
150 A
151 .BR renameat2 ()
152 call with a zero
153 .I flags
154 argument is equivalent to
155 .BR renameat ().
156 .P
157 The
158 .I flags
159 argument is a bit mask consisting of zero or more of the following flags:
160 .TP
161 .B RENAME_EXCHANGE
162 Atomically exchange
163 .I oldpath
164 and
165 .IR newpath .
166 Both pathnames must exist
167 but may be of different types (e.g., one could be a non-empty directory
168 and the other a symbolic link).
169 .TP
170 .B RENAME_NOREPLACE
171 Don't overwrite
172 .I newpath
173 of the rename.
174 Return an error if
175 .I newpath
176 already exists.
177 .IP
178 .B RENAME_NOREPLACE
179 can't be employed together with
180 .BR RENAME_EXCHANGE .
181 .IP
182 .B RENAME_NOREPLACE
183 requires support from the underlying filesystem.
184 Support for various filesystems was added as follows:
185 .RS
186 .IP \[bu] 3
187 ext4 (Linux 3.15);
188 .\" ext4: commit 0a7c3937a1f23f8cb5fc77ae01661e9968a51d0c
189 .IP \[bu]
190 btrfs, tmpfs, and cifs (Linux 3.17);
191 .IP \[bu]
192 xfs (Linux 4.0);
193 .\" btrfs: commit 80ace85c915d0f41016f82917218997b72431258
194 .\" tmpfs: commit 3b69ff51d087d265aa4af3a532fc4f20bf33e718
195 .\" cifs: commit 7c33d5972ce382bcc506d16235f1e9b7d22cbef8
196 .\"
197 .\" gfs2 in Linux 4.2?
198 .IP \[bu]
199 Support for many other filesystems was added in Linux 4.9, including
200 ext2, minix, reiserfs, jfs, vfat, and bpf.
201 .\" Also affs, bfs, exofs, hfs, hfsplus, jffs2, logfs, msdos,
202 .\" nilfs2, omfs, sysvfs, ubifs, udf, ufs
203 .\" hugetlbfs, ramfs
204 .\" local filesystems: commit f03b8ad8d38634d13e802165cc15917481b47835
205 .\" libfs: commit e0e0be8a835520e2f7c89f214dfda570922a1b90
206 .RE
207 .TP
208 .BR RENAME_WHITEOUT " (since Linux 3.18)"
209 .\" commit 0d7a855526dd672e114aff2ac22b60fc6f155b08
210 .\" commit 787fb6bc9682ec7c05fb5d9561b57100fbc1cc41
211 This operation makes sense only for overlay/union
212 filesystem implementations.
213 .IP
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 .IP
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 .IP
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)
231 and then renamed on the upper, read-write layer.
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 .IP
237 When not part of a union/overlay,
238 the whiteout appears as a character device with a {0,0} device number.
239 .\" https://www.freebsd.org/cgi/man.cgi?query=mount_unionfs&manpath=FreeBSD+11.0-RELEASE
240 (Note that other union/overlay implementations may employ different methods
241 for storing whiteout entries;
242 specifically,
243 BSD union mount employs
244 a separate inode type,
245 .BR DT_WHT ,
246 which,
247 while supported by some filesystems available in Linux,
248 such as CODA and XFS,
249 is ignored by the kernel's whiteout support code,
250 as of Linux 4.19, at least.)
251 .IP
252 .B RENAME_WHITEOUT
253 requires the same privileges as creating a device node (i.e., the
254 .B CAP_MKNOD
255 capability).
256 .IP
257 .B RENAME_WHITEOUT
258 can't be employed together with
259 .BR RENAME_EXCHANGE .
260 .IP
261 .B RENAME_WHITEOUT
262 requires support from the underlying filesystem.
263 Among the filesystems that support it are
264 tmpfs (since Linux 3.18),
265 .\" tmpfs: commit 46fdb794e3f52ef18b859ebc92f0a9d7db21c5df
266 ext4 (since Linux 3.18),
267 .\" ext4: commit cd808deced431b66b5fa4e5c193cb7ec0059eaff
268 XFS (since Linux 4.1),
269 .\" XFS: commit 7dcf5c3e4527cfa2807567b00387cf2ed5e07f00
270 f2fs (since Linux 4.2),
271 .\" f2fs: commit 7e01e7ad746bc8198a8b46163ddc73a1c7d22339
272 btrfs (since Linux 4.7),
273 .\" btrfs: commit cdd1fedf8261cd7a73c0596298902ff4f0f04492
274 and ubifs (since Linux 4.9).
275 .\" ubifs: commit 9e0a1fff8db56eaaebb74b4a3ef65f86811c4798
276 .SH RETURN VALUE
277 On success, zero is returned.
278 On error, \-1 is returned, and
279 .I errno
280 is set to indicate the error.
281 .SH ERRORS
282 .TP
283 .B EACCES
284 Write permission is denied for the directory containing
285 .I oldpath
286 or
287 .IR newpath ,
288 or, search permission is denied for one of the directories
289 in the path prefix of
290 .I oldpath
291 or
292 .IR newpath ,
293 or
294 .I oldpath
295 is a directory and does not allow write permission (needed to update
296 the
297 .I ..
298 entry).
299 (See also
300 .BR path_resolution (7).)
301 .TP
302 .B EBUSY
303 The rename fails because
304 .IR oldpath " or " newpath
305 is a directory that is in use by some process (perhaps as
306 current working directory, or as root directory, or because
307 it was open for reading) or is in use by the system
308 (for example as a mount point), while the system considers
309 this an error.
310 (Note that there is no requirement to return
311 .B EBUSY
312 in such
313 cases\[em]there is nothing wrong with doing the rename anyway\[em]but
314 it is allowed to return
315 .B EBUSY
316 if the system cannot otherwise
317 handle such situations.)
318 .TP
319 .B EDQUOT
320 The user's quota of disk blocks on the filesystem has been exhausted.
321 .TP
322 .B EFAULT
323 .IR oldpath " or " newpath " points outside your accessible address space."
324 .TP
325 .B EINVAL
326 The new pathname contained a path prefix of the old, or, more generally,
327 an attempt was made to make a directory a subdirectory of itself.
328 .TP
329 .B EISDIR
330 .I newpath
331 is an existing directory, but
332 .I oldpath
333 is not a directory.
334 .TP
335 .B ELOOP
336 Too many symbolic links were encountered in resolving
337 .IR oldpath " or " newpath .
338 .TP
339 .B EMLINK
340 .I oldpath
341 already has the maximum number of links to it, or
342 it was a directory and the directory containing
343 .I newpath
344 has the maximum number of links.
345 .TP
346 .B ENAMETOOLONG
347 .IR oldpath " or " newpath " was too long."
348 .TP
349 .B ENOENT
350 The link named by
351 .I oldpath
352 does not exist;
353 or, a directory component in
354 .I newpath
355 does not exist;
356 or,
357 .I oldpath
358 or
359 .I newpath
360 is an empty string.
361 .TP
362 .B ENOMEM
363 Insufficient kernel memory was available.
364 .TP
365 .B ENOSPC
366 The device containing the file has no room for the new directory
367 entry.
368 .TP
369 .B ENOTDIR
370 A component used as a directory in
371 .IR oldpath " or " newpath
372 is not, in fact, a directory.
373 Or,
374 .I oldpath
375 is a directory, and
376 .I newpath
377 exists but is not a directory.
378 .TP
379 .BR ENOTEMPTY " or " EEXIST
380 .I newpath
381 is a nonempty directory, that is, contains entries other than "." and "..".
382 .TP
383 .BR EPERM " or " EACCES
384 The directory containing
385 .I oldpath
386 has the sticky bit
387 .RB ( S_ISVTX )
388 set and the process's effective user ID is neither
389 the user ID of the file to be deleted nor that of the directory
390 containing it, and the process is not privileged
391 (Linux: does not have the
392 .B CAP_FOWNER
393 capability);
394 or
395 .I newpath
396 is an existing file and the directory containing it has the sticky bit set
397 and the process's effective user ID is neither the user ID of the file
398 to be replaced nor that of the directory containing it,
399 and the process is not privileged
400 (Linux: does not have the
401 .B CAP_FOWNER
402 capability);
403 or the filesystem containing
404 .I oldpath
405 does not support renaming of the type requested.
406 .TP
407 .B EROFS
408 The file is on a read-only filesystem.
409 .TP
410 .B EXDEV
411 .IR oldpath " and " newpath
412 are not on the same mounted filesystem.
413 (Linux permits a filesystem to be mounted at multiple points, but
414 .BR rename ()
415 does not work across different mount points,
416 even if the same filesystem is mounted on both.)
417 .P
418 The following additional errors can occur for
419 .BR renameat ()
420 and
421 .BR renameat2 ():
422 .TP
423 .B EBADF
424 .I oldpath
425 .RI ( newpath )
426 is relative but
427 .I olddirfd
428 .RI ( newdirfd )
429 is not a valid file descriptor.
430 .TP
431 .B ENOTDIR
432 .I oldpath
433 is relative and
434 .I olddirfd
435 is a file descriptor referring to a file other than a directory;
436 or similar for
437 .I newpath
438 and
439 .I newdirfd
440 .P
441 The following additional errors can occur for
442 .BR renameat2 ():
443 .TP
444 .B EEXIST
445 .I flags
446 contains
447 .B RENAME_NOREPLACE
448 and
449 .I newpath
450 already exists.
451 .TP
452 .B EINVAL
453 An invalid flag was specified in
454 .IR flags .
455 .TP
456 .B EINVAL
457 Both
458 .B RENAME_NOREPLACE
459 and
460 .B RENAME_EXCHANGE
461 were specified in
462 .IR flags .
463 .TP
464 .B EINVAL
465 Both
466 .B RENAME_WHITEOUT
467 and
468 .B RENAME_EXCHANGE
469 were specified in
470 .IR flags .
471 .TP
472 .B EINVAL
473 The filesystem does not support one of the flags in
474 .IR flags .
475 .TP
476 .B ENOENT
477 .I flags
478 contains
479 .B RENAME_EXCHANGE
480 and
481 .I newpath
482 does not exist.
483 .TP
484 .B EPERM
485 .B RENAME_WHITEOUT
486 was specified in
487 .IR flags ,
488 but the caller does not have the
489 .B CAP_MKNOD
490 capability.
491 .SH STANDARDS
492 .TP
493 .BR rename ()
494 C11, POSIX.1-2024.
495 .TP
496 .BR renameat ()
497 POSIX.1-2024.
498 .TP
499 .BR renameat2 ()
500 Linux.
501 .SH HISTORY
502 .TP
503 .BR rename ()
504 C89, POSIX.1-2001, 4.3BSD.
505 .TP
506 .BR renameat ()
507 POSIX.1-2008.
508 Linux 2.6.16,
509 glibc 2.4.
510 .TP
511 .BR renameat2 ()
512 Linux 3.15,
513 glibc 2.28.
514 .SS glibc notes
515 On older kernels where
516 .BR renameat ()
517 is unavailable, the glibc wrapper function falls back to the use of
518 .BR rename ().
519 When
520 .I oldpath
521 and
522 .I newpath
523 are relative pathnames,
524 glibc constructs pathnames based on the symbolic links in
525 .I /proc/self/fd
526 that correspond to the
527 .I olddirfd
528 and
529 .I newdirfd
530 arguments.
531 .SH BUGS
532 On NFS filesystems, you can not assume that if the operation
533 failed, the file was not renamed.
534 If the server does the rename operation
535 and then crashes, the retransmitted RPC which will be processed when the
536 server is up again causes a failure.
537 The application is expected to
538 deal with this.
539 See
540 .BR link (2)
541 for a similar problem.
542 .SH SEE ALSO
543 .BR mv (1),
544 .BR rename (1),
545 .BR chmod (2),
546 .BR link (2),
547 .BR symlink (2),
548 .BR unlink (2),
549 .BR path_resolution (7),
550 .BR symlink (7)