man2/rename.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\"             and Copyright (C) 1993 Michael Haardt;
   3 .\"             and Copyright (C) 1993,1995 Ian Jackson
   4 .\"             and Copyright (C) 2006, 2014 Michael Kerrisk
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .\" Modified Sat Jul 24 00:35:52 1993 by Rik Faith <faith@cs.unc.edu>
   9 .\" Modified Thu Jun  4 12:21:13 1998 by Andries Brouwer <aeb@cwi.nl>
  10 .\" Modified Thu Mar  3 09:49:35 2005 by Michael Haardt <michael@moria.de>
  11 .\" 2007-03-25, mtk, added various text to DESCRIPTION.
  12 .\"
  13 .TH RENAME 2 2021-08-27 "Linux man-pages (unreleased)"
  14 .SH NAME
  15 rename, renameat, renameat2 \- change the name or location of a file
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <stdio.h>
  22 .PP
  23 .BI "int rename(const char *" oldpath ", const char *" newpath );
  24 .PP
  25 .BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
  26 .B #include <stdio.h>
  27 .PP
  28 .BI "int renameat(int " olddirfd ", const char *" oldpath ,
  29 .BI "             int " newdirfd ", const char *" newpath );
  30 .BI "int renameat2(int " olddirfd ", const char *" oldpath ,
  31 .BI "             int " newdirfd ", const char *" newpath \
  32 ", unsigned int " flags );
  33 .fi
  34 .PP
  35 .RS -4
  36 Feature Test Macro Requirements for glibc (see
  37 .BR feature_test_macros (7)):
  38 .RE
  39 .PP
  40 .nf
  41 .BR renameat ():
  42     Since glibc 2.10:
  43         _POSIX_C_SOURCE >= 200809L
  44     Before glibc 2.10:
  45         _ATFILE_SOURCE
  46 .PP
  47 .BR renameat2 ():
  48     _GNU_SOURCE
  49 .fi
  50 .SH DESCRIPTION
  51 .BR rename ()
  52 renames a file, moving it between directories if required.
  53 Any other hard links to the file (as created using
  54 .BR link (2))
  55 are unaffected.
  56 Open file descriptors for
  57 .I oldpath
  58 are also unaffected.
  59 .PP
  60 Various restrictions determine whether or not the rename operation succeeds:
  61 see ERRORS below.
  62 .PP
  63 If
  64 .I newpath
  65 already exists, it will be atomically replaced, so that there is
  66 no point at which another process attempting to access
  67 .I newpath
  68 will find it missing.
  69 However, there will probably be a window in which both
  70 .I oldpath
  71 and
  72 .I newpath
  73 refer to the file being renamed.
  74 .PP
  75 If
  76 .I oldpath
  77 and
  78 .I newpath
  79 are existing hard links referring to the same file, then
  80 .BR rename ()
  81 does nothing, and returns a success status.
  82 .PP
  83 If
  84 .I newpath
  85 exists but the operation fails for some reason,
  86 .BR rename ()
  87 guarantees to leave an instance of
  88 .I newpath
  89 in place.
  90 .PP
  91 .I oldpath
  92 can specify a directory.
  93 In this case,
  94 .I newpath
  95 must either not exist, or it must specify an empty directory.
  96 .PP
  97 If
  98 .I oldpath
  99 refers to a symbolic link, the link is renamed; if
 100 .I newpath
 101 refers to a symbolic link, the link will be overwritten.
 102 .SS renameat()
 103 The
 104 .BR renameat ()
 105 system call operates in exactly the same way as
 106 .BR rename (),
 107 except for the differences described here.
 108 .PP
 109 If the pathname given in
 110 .I oldpath
 111 is relative, then it is interpreted relative to the directory
 112 referred to by the file descriptor
 113 .I olddirfd
 114 (rather than relative to the current working directory of
 115 the calling process, as is done by
 116 .BR rename ()
 117 for a relative pathname).
 118 .PP
 119 If
 120 .I oldpath
 121 is relative and
 122 .I olddirfd
 123 is the special value
 124 .BR AT_FDCWD ,
 125 then
 126 .I oldpath
 127 is interpreted relative to the current working
 128 directory of the calling process (like
 129 .BR rename ()).
 130 .PP
 131 If
 132 .I oldpath
 133 is absolute, then
 134 .I olddirfd
 135 is ignored.
 136 .PP
 137 The interpretation of
 138 .I newpath
 139 is as for
 140 .IR oldpath ,
 141 except that a relative pathname is interpreted relative
 142 to the directory referred to by the file descriptor
 143 .IR newdirfd .
 144 .PP
 145 See
 146 .BR openat (2)
 147 for an explanation of the need for
 148 .BR renameat ().
 149 .SS renameat2()
 150 .BR renameat2 ()
 151 has an additional
 152 .I flags
 153 argument.
 154 A
 155 .BR renameat2 ()
 156 call with a zero
 157 .I flags
 158 argument is equivalent to
 159 .BR renameat ().
 160 .PP
 161 The
 162 .I flags
 163 argument is a bit mask consisting of zero or more of the following flags:
 164 .TP
 165 .B RENAME_EXCHANGE
 166 Atomically exchange
 167 .I oldpath
 168 and
 169 .IR newpath .
 170 Both pathnames must exist
 171 but may be of different types (e.g., one could be a non-empty directory
 172 and the other a symbolic link).
 173 .TP
 174 .B RENAME_NOREPLACE
 175 Don't overwrite
 176 .I newpath
 177 of the rename.
 178 Return an error if
 179 .I newpath
 180 already exists.
 181 .IP
 182 .B RENAME_NOREPLACE
 183 can't be employed together with
 184 .BR RENAME_EXCHANGE .
 185 .IP
 186 .B RENAME_NOREPLACE
 187 requires support from the underlying filesystem.
 188 Support for various filesystems was added as follows:
 189 .RS
 190 .IP * 3
 191 ext4 (Linux 3.15);
 192 .\" ext4: commit 0a7c3937a1f23f8cb5fc77ae01661e9968a51d0c
 193 .IP *
 194 btrfs, tmpfs, and cifs (Linux 3.17);
 195 .IP *
 196 xfs (Linux 4.0);
 197 .\" btrfs: commit 80ace85c915d0f41016f82917218997b72431258
 198 .\" tmpfs: commit 3b69ff51d087d265aa4af3a532fc4f20bf33e718
 199 .\" cifs: commit 7c33d5972ce382bcc506d16235f1e9b7d22cbef8
 200 .\"
 201 .\" gfs2 in 4.2?
 202 .IP *
 203 Support for many other filesystems was added in Linux 4.9, including
 204 ext2, minix, reiserfs, jfs, vfat, and bpf.
 205 .\" Also affs, bfs, exofs, hfs, hfsplus, jffs2, logfs, msdos,
 206 .\" nilfs2, omfs, sysvfs, ubifs, udf, ufs
 207 .\" hugetlbfs, ramfs
 208 .\" local filesystems: commit f03b8ad8d38634d13e802165cc15917481b47835
 209 .\" libfs: commit e0e0be8a835520e2f7c89f214dfda570922a1b90
 210 .RE
 211 .TP
 212 .BR RENAME_WHITEOUT " (since Linux 3.18)"
 213 .\" commit 0d7a855526dd672e114aff2ac22b60fc6f155b08
 214 .\" commit 787fb6bc9682ec7c05fb5d9561b57100fbc1cc41
 215 This operation makes sense only for overlay/union
 216 filesystem implementations.
 217 .IP
 218 Specifying
 219 .B RENAME_WHITEOUT
 220 creates a "whiteout" object at the source of
 221 the rename at the same time as performing the rename.
 222 The whole operation is atomic,
 223 so that if the rename succeeds then the whiteout will also have been created.
 224 .IP
 225 A "whiteout" is an object that has special meaning in union/overlay
 226 filesystem constructs.
 227 In these constructs,
 228 multiple layers exist and only the top one is ever modified.
 229 A whiteout on an upper layer will effectively hide a
 230 matching file in the lower layer,
 231 making it appear as if the file didn't exist.
 232 .IP
 233 When a file that exists on the lower layer is renamed,
 234 the file is first copied up (if not already on the upper layer)
 235 and then renamed on the upper, read-write layer.
 236 At the same time, the source file needs to be "whiteouted"
 237 (so that the version of the source file in the lower layer
 238 is rendered invisible).
 239 The whole operation needs to be done atomically.
 240 .IP
 241 When not part of a union/overlay,
 242 the whiteout appears as a character device with a {0,0} device number.
 243 .\" https://www.freebsd.org/cgi/man.cgi?query=mount_unionfs&manpath=FreeBSD+11.0-RELEASE
 244 (Note that other union/overlay implementations may employ different methods
 245 for storing whiteout entries; specifically, BSD union mount employs
 246 a separate inode type,
 247 .BR DT_WHT ,
 248 which, while supported by some filesystems available in Linux,
 249 such as CODA and XFS, 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\(emthere is nothing wrong with doing the rename anyway\(embut
 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 .PP
 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 .PP
 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 VERSIONS
 492 .BR renameat ()
 493 was added to Linux in kernel 2.6.16;
 494 library support was added to glibc in version 2.4.
 495 .PP
 496 .BR renameat2 ()
 497 was added to Linux in kernel 3.15; library support was added in glibc 2.28.
 498 .SH STANDARDS
 499 .BR rename ():
 500 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.
 501 .PP
 502 .BR renameat ():
 503 POSIX.1-2008.
 504 .PP
 505 .BR renameat2 ()
 506 is Linux-specific.
 507 .SH NOTES
 508 .\"
 509 .SS Glibc notes
 510 On older kernels where
 511 .BR renameat ()
 512 is unavailable, the glibc wrapper function falls back to the use of
 513 .BR rename ().
 514 When
 515 .I oldpath
 516 and
 517 .I newpath
 518 are relative pathnames,
 519 glibc constructs pathnames based on the symbolic links in
 520 .I /proc/self/fd
 521 that correspond to the
 522 .I olddirfd
 523 and
 524 .I newdirfd
 525 arguments.
 526 .SH BUGS
 527 On NFS filesystems, you can not assume that if the operation
 528 failed, the file was not renamed.
 529 If the server does the rename operation
 530 and then crashes, the retransmitted RPC which will be processed when the
 531 server is up again causes a failure.
 532 The application is expected to
 533 deal with this.
 534 See
 535 .BR link (2)
 536 for a similar problem.
 537 .SH SEE ALSO
 538 .BR mv (1),
 539 .BR rename (1),
 540 .BR chmod (2),
 541 .BR link (2),
 542 .BR symlink (2),
 543 .BR unlink (2),
 544 .BR path_resolution (7),
 545 .BR symlink (7)