original/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-05-08 "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_NOREPLACE
 188 Don't overwrite
 189 .IR newpath .
 190 of the rename.
 191 Return an error if
 192 .IR newpath
 193 already exists.
 194 .TP
 195 .B RENAME_EXCHANGE
 196 Atomically exchange
 197 .IR oldpath
 198 and
 199 .IR newpath .
 200 Both pathnames must exist
 201 but may be of different types (e.g., one could be a non-empty directory
 202 and the other a symbolic link).
 203 .SH RETURN VALUE
 204 On success, zero is returned.
 205 On error, \-1 is returned, and
 206 .I errno
 207 is set appropriately.
 208 .SH ERRORS
 209 .TP
 210 .B EACCES
 211 Write permission is denied for the directory containing
 212 .I oldpath
 213 or
 214 .IR newpath ,
 215 or, search permission is denied for one of the directories
 216 in the path prefix of
 217 .I oldpath
 218 or
 219 .IR newpath ,
 220 or
 221 .I oldpath
 222 is a directory and does not allow write permission (needed to update
 223 the
 224 .I ..
 225 entry).
 226 (See also
 227 .BR path_resolution (7).)
 228 .TP
 229 .B EBUSY
 230 The rename fails because
 231 .IR oldpath " or " newpath
 232 is a directory that is in use by some process (perhaps as
 233 current working directory, or as root directory, or because
 234 it was open for reading) or is in use by the system
 235 (for example as mount point), while the system considers
 236 this an error.
 237 (Note that there is no requirement to return
 238 .B EBUSY
 239 in such
 240 cases\(emthere is nothing wrong with doing the rename anyway\(embut
 241 it is allowed to return
 242 .B EBUSY
 243 if the system cannot otherwise
 244 handle such situations.)
 245 .TP
 246 .B EDQUOT
 247 The user's quota of disk blocks on the filesystem has been exhausted.
 248 .TP
 249 .B EFAULT
 250 .IR oldpath " or " newpath " points outside your accessible address space."
 251 .TP
 252 .B EINVAL
 253 The new pathname contained a path prefix of the old, or, more generally,
 254 an attempt was made to make a directory a subdirectory of itself.
 255 .TP
 256 .B EISDIR
 257 .I newpath
 258 is an existing directory, but
 259 .I oldpath
 260 is not a directory.
 261 .TP
 262 .B ELOOP
 263 Too many symbolic links were encountered in resolving
 264 .IR oldpath " or " newpath .
 265 .TP
 266 .B EMLINK
 267 .I oldpath
 268 already has the maximum number of links to it, or
 269 it was a directory and the directory containing
 270 .I newpath
 271 has the maximum number of links.
 272 .TP
 273 .B ENAMETOOLONG
 274 .IR oldpath " or " newpath " was too long."
 275 .TP
 276 .B ENOENT
 277 The link named by
 278 .I oldpath
 279 does not exist;
 280 or, a directory component in
 281 .I newpath
 282 does not exist;
 283 or,
 284 .I oldpath
 285 or
 286 .I newpath
 287 is an empty string.
 288 .TP
 289 .B ENOMEM
 290 Insufficient kernel memory was available.
 291 .TP
 292 .B ENOSPC
 293 The device containing the file has no room for the new directory
 294 entry.
 295 .TP
 296 .B ENOTDIR
 297 A component used as a directory in
 298 .IR oldpath " or " newpath
 299 is not, in fact, a directory.
 300 Or,
 301 .I oldpath
 302 is a directory, and
 303 .I newpath
 304 exists but is not a directory.
 305 .TP
 306 .BR ENOTEMPTY " or " EEXIST
 307 .I newpath
 308 is a nonempty directory, that is, contains entries other than "." and "..".
 309 .TP
 310 .BR EPERM " or " EACCES
 311 The directory containing
 312 .I oldpath
 313 has the sticky bit
 314 .RB ( S_ISVTX )
 315 set and the process's effective user ID is neither
 316 the user ID of the file to be deleted nor that of the directory
 317 containing it, and the process is not privileged
 318 (Linux: does not have the
 319 .B CAP_FOWNER
 320 capability);
 321 or
 322 .I newpath
 323 is an existing file and the directory containing it has the sticky bit set
 324 and the process's effective user ID is neither the user ID of the file
 325 to be replaced nor that of the directory containing it,
 326 and the process is not privileged
 327 (Linux: does not have the
 328 .B CAP_FOWNER
 329 capability);
 330 or the filesystem containing
 331 .I pathname
 332 does not support renaming of the type requested.
 333 .TP
 334 .B EROFS
 335 The file is on a read-only filesystem.
 336 .TP
 337 .B EXDEV
 338 .IR oldpath " and " newpath
 339 are not on the same mounted filesystem.
 340 (Linux permits a filesystem to be mounted at multiple points, but
 341 .BR rename ()
 342 does not work across different mount points,
 343 even if the same filesystem is mounted on both.)
 344 .PP
 345 The following additional errors can occur for
 346 .BR renameat ()
 347 and
 348 .BR renameat2 ():
 349 .TP
 350 .B EBADF
 351 .I olddirfd
 352 or
 353 .I newdirfd
 354 is not a valid file descriptor.
 355 .TP
 356 .B ENOTDIR
 357 .I oldpath
 358 is relative and
 359 .I olddirfd
 360 is a file descriptor referring to a file other than a directory;
 361 or similar for
 362 .I newpath
 363 and
 364 .I newdirfd
 365 .PP
 366 The following additional errors can occur for
 367 .BR renameat2 ():
 368 .TP
 369 .B EEXIST
 370 .I flags
 371 contains
 372 .B RENAME_NOREPLACE
 373 and
 374 .I newpath
 375 already exists.
 376 .TP
 377 .B EINVAL
 378 An invalid flag was specified in
 379 .IR flags ,
 380 or both
 381 .B RENAME_NOREPLACE
 382 and
 383 .B RENAME_EXCHANGE
 384 were specified.
 385 .TP
 386 .B EINVAL
 387 The filesystem does not support one of the flags in
 388 .IR flags .
 389 .TP
 390 .B ENOENT
 391 .I flags
 392 contains
 393 .B RENAME_EXCHANGE
 394 and
 395 .IR newpath
 396 does not exist.
 397 .SH VERSIONS
 398 .BR renameat ()
 399 was added to Linux in kernel 2.6.16;
 400 library support was added to glibc in version 2.4.
 401
 402 .BR renameat2 ()
 403 was added to Linux in kernel 3.15.
 404 .\" FIXME glibc support is pending.
 405 .SH CONFORMING TO
 406 .BR rename ():
 407 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.
 408
 409 .BR renameat ():
 410 POSIX.1-2008.
 411
 412 .BR renameat2()
 413 is Linux-specific.
 414 .SH BUGS
 415 On NFS filesystems, you can not assume that if the operation
 416 failed, the file was not renamed.
 417 If the server does the rename operation
 418 and then crashes, the retransmitted RPC which will be processed when the
 419 server is up again causes a failure.
 420 The application is expected to
 421 deal with this.
 422 See
 423 .BR link (2)
 424 for a similar problem.
 425 .SH SEE ALSO
 426 .BR mv (1),
 427 .BR chmod (2),
 428 .BR link (2),
 429 .BR symlink (2),
 430 .BR unlink (2),
 431 .BR path_resolution (7),
 432 .BR symlink (7)
 433 .SH COLOPHON
 434 This page is part of release 3.68 of the Linux
 435 .I man-pages
 436 project.
 437 A description of the project,
 438 information about reporting bugs,
 439 and the latest version of this page,
 440 can be found at
 441 \%http://www.kernel.org/doc/man\-pages/.