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 2014-08-19 "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 .sp
  40 .BI "int rename(const char *" oldpath ", const char *" newpath );
  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 );
  47
  48 .BI "int renameat2(int " olddirfd ", const char *" oldpath ,
  49 .BI "              int " newdirfd ", const char *" newpath \
  50 ", unsigned int " flags );
  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
  68 .\" FIXME . need to define FTMs for renameat2(), once it hits glibc
  69 .RE
  70 .ad
  71 .PD
  72 .SH DESCRIPTION
  73 .BR rename ()
  74 renames a file, moving it between directories if required.
  75 Any other hard links to the file (as created using
  76 .BR link (2))
  77 are unaffected.
  78 Open file descriptors for
  79 .I oldpath
  80 are also unaffected.
  81
  82 If
  83 .I newpath
  84 already exists, it will be atomically replaced (subject to
  85 a few conditions; see ERRORS below), so that there is
  86 no point at which another process attempting to access
  87 .I newpath
  88 will find it missing.
  89
  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
  98 If
  99 .I newpath
 100 exists but the operation fails for some reason,
 101 .BR rename ()
 102 guarantees to leave an instance of
 103 .I newpath
 104 in place.
 105
 106 .I oldpath
 107 can specify a directory.
 108 In this case,
 109 .I newpath
 110 must either not exist, or it must specify an empty directory.
 111
 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
 121 refers to a symbolic link, the link is renamed; if
 122 .I newpath
 123 refers to a symbolic link, the link will be overwritten.
 124 .SS renameat()
 125 The
 126 .BR renameat ()
 127 system call operates in exactly the same way as
 128 .BR rename (),
 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
 138 .BR rename ()
 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
 151 .BR rename ()).
 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 ().
 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
 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).
 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.
 203
 204 .B RENAME_NOREPLACE
 205 can't be employed together with
 206 .BR RENAME_EXCHANGE .
 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
 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)
 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
 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
 258 .SH RETURN VALUE
 259 On success, zero is returned.
 260 On error, \-1 is returned, and
 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
 279 .I ..
 280 entry).
 281 (See also
 282 .BR path_resolution (7).)
 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.
 292 (Note that there is no requirement to return
 293 .B EBUSY
 294 in such
 295 cases\(emthere is nothing wrong with doing the rename anyway\(embut
 296 it is allowed to return
 297 .B EBUSY
 298 if the system cannot otherwise
 299 handle such situations.)
 300 .TP
 301 .B EDQUOT
 302 The user's quota of disk blocks on the filesystem has been exhausted.
 303 .TP
 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
 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.
 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
 362 .I newpath
 363 is a nonempty directory, that is, contains entries other than "." and "..".
 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);
 385 or the filesystem containing
 386 .I pathname
 387 does not support renaming of the type requested.
 388 .TP
 389 .B EROFS
 390 The file is on a read-only filesystem.
 391 .TP
 392 .B EXDEV
 393 .IR oldpath " and " newpath
 394 are not on the same mounted filesystem.
 395 (Linux permits a filesystem to be mounted at multiple points, but
 396 .BR rename ()
 397 does not work across different mount points,
 398 even if the same filesystem is mounted on both.)
 399 .PP
 400 The following additional errors can occur for
 401 .BR renameat ()
 402 and
 403 .BR renameat2 ():
 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
 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.
 431 .TP
 432 .B EINVAL
 433 An invalid flag was specified in
 434 .IR flags .
 435 .TP
 436 .B EINVAL
 437 Both
 438 .B RENAME_NOREPLACE
 439 and
 440 .B RENAME_EXCHANGE
 441 were specified in
 442 .IR flags .
 443 .TP
 444 .B EINVAL
 445 Both
 446 .B RENAME_WHITEOUT
 447 and
 448 .B RENAME_EXCHANGE
 449 were specified in
 450 .IR flags .
 451 .TP
 452 .B EINVAL
 453 The filesystem does not support one of the flags in
 454 .IR flags .
 455 .TP
 456 .B ENOENT
 457 .I flags
 458 contains
 459 .B RENAME_EXCHANGE
 460 and
 461 .IR newpath
 462 does not exist.
 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.
 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.
 475
 476 .BR renameat2 ()
 477 was added to Linux in kernel 3.15.
 478 .\" FIXME . glibc support is pending.
 479 .SH CONFORMING TO
 480 .BR rename ():
 481 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.
 482
 483 .BR renameat ():
 484 POSIX.1-2008.
 485
 486 .BR renameat2 ()
 487 is Linux-specific.
 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.
 506 .SH BUGS
 507 On NFS filesystems, you can not assume that if the operation
 508 failed, the file was not renamed.
 509 If the server does the rename operation
 510 and then crashes, the retransmitted RPC which will be processed when the
 511 server is up again causes a failure.
 512 The application is expected to
 513 deal with this.
 514 See
 515 .BR link (2)
 516 for a similar problem.
 517 .SH SEE ALSO
 518 .BR mv (1),
 519 .BR chmod (2),
 520 .BR link (2),
 521 .BR symlink (2),
 522 .BR unlink (2),
 523 .BR path_resolution (7),
 524 .BR symlink (7)