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