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 2017-09-15 "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 etx2, 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 .IP
 271 .B RENAME_WHITEOUT
 272 requires the same privileges as creating a device node (i.e., the
 273 .BR CAP_MKNOD
 274 capability).
 275 .IP
 276 .B RENAME_WHITEOUT
 277 can't be employed together with
 278 .BR RENAME_EXCHANGE .
 279 .IP
 280 .B RENAME_WHITEOUT
 281 requires support from the underlying filesystem.
 282 Among the filesystems that provide that support are
 283 tmpfs (since Linux 3.18),
 284 .\" tmpfs: commit 46fdb794e3f52ef18b859ebc92f0a9d7db21c5df
 285 ext4 (since Linux 3.18),
 286 .\" ext4: commit cd808deced431b66b5fa4e5c193cb7ec0059eaff
 287 and XFS (since Linux 4.1).
 288 .\" XFS: commit 7dcf5c3e4527cfa2807567b00387cf2ed5e07f00
 289 .SH RETURN VALUE
 290 On success, zero is returned.
 291 On error, \-1 is returned, and
 292 .I errno
 293 is set appropriately.
 294 .SH ERRORS
 295 .TP
 296 .B EACCES
 297 Write permission is denied for the directory containing
 298 .I oldpath
 299 or
 300 .IR newpath ,
 301 or, search permission is denied for one of the directories
 302 in the path prefix of
 303 .I oldpath
 304 or
 305 .IR newpath ,
 306 or
 307 .I oldpath
 308 is a directory and does not allow write permission (needed to update
 309 the
 310 .I ..
 311 entry).
 312 (See also
 313 .BR path_resolution (7).)
 314 .TP
 315 .B EBUSY
 316 The rename fails because
 317 .IR oldpath " or " newpath
 318 is a directory that is in use by some process (perhaps as
 319 current working directory, or as root directory, or because
 320 it was open for reading) or is in use by the system
 321 (for example as mount point), while the system considers
 322 this an error.
 323 (Note that there is no requirement to return
 324 .B EBUSY
 325 in such
 326 cases\(emthere is nothing wrong with doing the rename anyway\(embut
 327 it is allowed to return
 328 .B EBUSY
 329 if the system cannot otherwise
 330 handle such situations.)
 331 .TP
 332 .B EDQUOT
 333 The user's quota of disk blocks on the filesystem has been exhausted.
 334 .TP
 335 .B EFAULT
 336 .IR oldpath " or " newpath " points outside your accessible address space."
 337 .TP
 338 .B EINVAL
 339 The new pathname contained a path prefix of the old, or, more generally,
 340 an attempt was made to make a directory a subdirectory of itself.
 341 .TP
 342 .B EISDIR
 343 .I newpath
 344 is an existing directory, but
 345 .I oldpath
 346 is not a directory.
 347 .TP
 348 .B ELOOP
 349 Too many symbolic links were encountered in resolving
 350 .IR oldpath " or " newpath .
 351 .TP
 352 .B EMLINK
 353 .I oldpath
 354 already has the maximum number of links to it, or
 355 it was a directory and the directory containing
 356 .I newpath
 357 has the maximum number of links.
 358 .TP
 359 .B ENAMETOOLONG
 360 .IR oldpath " or " newpath " was too long."
 361 .TP
 362 .B ENOENT
 363 The link named by
 364 .I oldpath
 365 does not exist;
 366 or, a directory component in
 367 .I newpath
 368 does not exist;
 369 or,
 370 .I oldpath
 371 or
 372 .I newpath
 373 is an empty string.
 374 .TP
 375 .B ENOMEM
 376 Insufficient kernel memory was available.
 377 .TP
 378 .B ENOSPC
 379 The device containing the file has no room for the new directory
 380 entry.
 381 .TP
 382 .B ENOTDIR
 383 A component used as a directory in
 384 .IR oldpath " or " newpath
 385 is not, in fact, a directory.
 386 Or,
 387 .I oldpath
 388 is a directory, and
 389 .I newpath
 390 exists but is not a directory.
 391 .TP
 392 .BR ENOTEMPTY " or " EEXIST
 393 .I newpath
 394 is a nonempty directory, that is, contains entries other than "." and "..".
 395 .TP
 396 .BR EPERM " or " EACCES
 397 The directory containing
 398 .I oldpath
 399 has the sticky bit
 400 .RB ( S_ISVTX )
 401 set and the process's effective user ID is neither
 402 the user ID of the file to be deleted nor that of the directory
 403 containing it, and the process is not privileged
 404 (Linux: does not have the
 405 .B CAP_FOWNER
 406 capability);
 407 or
 408 .I newpath
 409 is an existing file and the directory containing it has the sticky bit set
 410 and the process's effective user ID is neither the user ID of the file
 411 to be replaced nor that of the directory containing it,
 412 and the process is not privileged
 413 (Linux: does not have the
 414 .B CAP_FOWNER
 415 capability);
 416 or the filesystem containing
 417 .I pathname
 418 does not support renaming of the type requested.
 419 .TP
 420 .B EROFS
 421 The file is on a read-only filesystem.
 422 .TP
 423 .B EXDEV
 424 .IR oldpath " and " newpath
 425 are not on the same mounted filesystem.
 426 (Linux permits a filesystem to be mounted at multiple points, but
 427 .BR rename ()
 428 does not work across different mount points,
 429 even if the same filesystem is mounted on both.)
 430 .PP
 431 The following additional errors can occur for
 432 .BR renameat ()
 433 and
 434 .BR renameat2 ():
 435 .TP
 436 .B EBADF
 437 .I olddirfd
 438 or
 439 .I newdirfd
 440 is not a valid file descriptor.
 441 .TP
 442 .B ENOTDIR
 443 .I oldpath
 444 is relative and
 445 .I olddirfd
 446 is a file descriptor referring to a file other than a directory;
 447 or similar for
 448 .I newpath
 449 and
 450 .I newdirfd
 451 .PP
 452 The following additional errors can occur for
 453 .BR renameat2 ():
 454 .TP
 455 .B EEXIST
 456 .I flags
 457 contains
 458 .B RENAME_NOREPLACE
 459 and
 460 .I newpath
 461 already exists.
 462 .TP
 463 .B EINVAL
 464 An invalid flag was specified in
 465 .IR flags .
 466 .TP
 467 .B EINVAL
 468 Both
 469 .B RENAME_NOREPLACE
 470 and
 471 .B RENAME_EXCHANGE
 472 were specified in
 473 .IR flags .
 474 .TP
 475 .B EINVAL
 476 Both
 477 .B RENAME_WHITEOUT
 478 and
 479 .B RENAME_EXCHANGE
 480 were specified in
 481 .IR flags .
 482 .TP
 483 .B EINVAL
 484 The filesystem does not support one of the flags in
 485 .IR flags .
 486 .TP
 487 .B ENOENT
 488 .I flags
 489 contains
 490 .B RENAME_EXCHANGE
 491 and
 492 .IR newpath
 493 does not exist.
 494 .TP
 495 .B EPERM
 496 .B RENAME_WHITEOUT
 497 was specified in
 498 .IR flags ,
 499 but the caller does not have the
 500 .B CAP_MKNOD
 501 capability.
 502 .SH VERSIONS
 503 .BR renameat ()
 504 was added to Linux in kernel 2.6.16;
 505 library support was added to glibc in version 2.4.
 506 .PP
 507 .BR renameat2 ()
 508 was added to Linux in kernel 3.15; library support was added in glibc 2.28.
 509 .SH CONFORMING TO
 510 .BR rename ():
 511 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.
 512 .PP
 513 .BR renameat ():
 514 POSIX.1-2008.
 515 .PP
 516 .BR renameat2 ()
 517 is Linux-specific.
 518 .SH NOTES
 519 .\"
 520 .SS Glibc notes
 521 On older kernels where
 522 .BR renameat ()
 523 is unavailable, the glibc wrapper function falls back to the use of
 524 .BR rename ().
 525 When
 526 .I oldpath
 527 and
 528 .I newpath
 529 are relative pathnames,
 530 glibc constructs pathnames based on the symbolic links in
 531 .IR /proc/self/fd
 532 that correspond to the
 533 .I olddirfd
 534 and
 535 .IR newdirfd
 536 arguments.
 537 .SH BUGS
 538 On NFS filesystems, you can not assume that if the operation
 539 failed, the file was not renamed.
 540 If the server does the rename operation
 541 and then crashes, the retransmitted RPC which will be processed when the
 542 server is up again causes a failure.
 543 The application is expected to
 544 deal with this.
 545 See
 546 .BR link (2)
 547 for a similar problem.
 548 .SH SEE ALSO
 549 .BR mv (1),
 550 .BR chmod (2),
 551 .BR link (2),
 552 .BR symlink (2),
 553 .BR unlink (2),
 554 .BR path_resolution (7),
 555 .BR symlink (7)