1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd August 25, 2024 29.Dt RENAME 2 30.Os 31.Sh NAME 32.Nm rename 33.Nd change the name of a file 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In stdio.h 38.Ft int 39.Fn rename "const char *from" "const char *to" 40.Ft int 41.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" 42.In sys/fcntl.h 43.In stdio.h 44.Ft int 45.Fo renameat2 46.Fa "int fromfd" 47.Fa "const char *from" 48.Fa "int tofd" 49.Fa "const char *to" 50.Fa "unsigned int flags" 51.Fc 52.Sh DESCRIPTION 53The 54.Fn rename 55system call 56causes the link named 57.Fa from 58to be renamed as 59.Fa to . 60If 61.Fa to 62exists, it is first removed. 63Both 64.Fa from 65and 66.Fa to 67must be of the same type (that is, both directories or both 68non-directories), and must reside on the same file system. 69.Pp 70The 71.Fn rename 72system call 73guarantees that if 74.Fa to 75already exists, an instance of 76.Fa to 77will always exist, even if the system should crash in 78the middle of the operation. 79.Pp 80If the final component of 81.Fa from 82is a symbolic link, 83the symbolic link is renamed, 84not the file or directory to which it points. 85.Pp 86If 87.Fa from 88and 89.Fa to 90resolve to the same directory entry, or to different directory 91entries for the same existing file, 92.Fn rename 93returns success without taking any further action. 94.Pp 95The 96.Fn renameat 97system call is equivalent to 98.Fn rename 99except in the case where either 100.Fa from 101or 102.Fa to 103specifies a relative path. 104If 105.Fa from 106is a relative path, the file to be renamed is located 107relative to the directory associated with the file descriptor 108.Fa fromfd 109instead of the current working directory. 110If the 111.Fa to 112is a relative path, the same happens only relative to the directory associated 113with 114.Fa tofd . 115If the 116.Fn renameat 117is passed the special value 118.Dv AT_FDCWD 119in the 120.Fa fromfd 121or 122.Fa tofd 123parameter, the current working directory is used in the determination 124of the file for the respective path parameter. 125.Pp 126The 127.Fn renameat2 128system call takes an additional 129.Fa flags 130argument. 131If 132.Fa flags 133is zero, the 134.Fn renameat2 135call operates identically to 136.Fn renameat . 137Additionally, the following flags can be specified: 138.Bl -tag -width AT_RENAME_NOREPLACE 139.It Dv AT_RENAME_NOREPLACE 140If the path specified by 141.Fa tofd 142and 143.Fa to 144exists, the request fails with the error 145.Er EEXIST . 146.It Dv AT_RENAME_EXCHANGE 147Atomically exchange the files pointed to by the 148.Fa from 149and 150.Fa to 151names. 152.El 153.Sh RETURN VALUES 154.Rv -std rename 155.Sh ERRORS 156The 157.Fn rename 158system call 159will fail and neither of the argument files will be 160affected if: 161.Bl -tag -width Er 162.It Bq Er ENAMETOOLONG 163A component of either pathname exceeded 255 characters, 164or the entire length of either path name exceeded 1023 characters. 165.It Bq Er ENOENT 166A component of the 167.Fa from 168path does not exist, 169or a path prefix of 170.Fa to 171does not exist. 172.It Bq Er EACCES 173A component of either path prefix denies search permission. 174.It Bq Er EACCES 175The requested link requires writing in a directory with a mode 176that denies write permission. 177.It Bq Er EACCES 178The directory pointed at by the 179.Fa from 180argument denies write permission, and the operation would move 181it to another parent directory. 182.It Bq Er EPERM 183The file pointed at by the 184.Fa from 185argument has its immutable, undeletable or append-only flag set, see the 186.Xr chflags 2 187manual page for more information. 188.It Bq Er EPERM 189The parent directory of the file pointed at by the 190.Fa from 191argument has its immutable or append-only flag set. 192.It Bq Er EPERM 193The parent directory of the file pointed at by the 194.Fa to 195argument has its immutable flag set. 196.It Bq Er EPERM 197The directory containing 198.Fa from 199is marked sticky, 200and neither the containing directory nor 201.Fa from 202are owned by the effective user ID. 203.It Bq Er EPERM 204The file pointed at by the 205.Fa to 206argument 207exists, 208the directory containing 209.Fa to 210is marked sticky, 211and neither the containing directory nor 212.Fa to 213are owned by the effective user ID. 214.It Bq Er ELOOP 215Too many symbolic links were encountered in translating either pathname. 216.It Bq Er ENOTDIR 217A component of either path prefix is not a directory. 218.It Bq Er ENOTDIR 219The 220.Fa from 221argument 222is a directory, but 223.Fa to 224is not a directory. 225.It Bq Er EISDIR 226The 227.Fa to 228argument 229is a directory, but 230.Fa from 231is not a directory. 232.It Bq Er EXDEV 233The link named by 234.Fa to 235and the file named by 236.Fa from 237are on different logical devices (file systems). 238Note that this error 239code will not be returned if the implementation permits cross-device 240links. 241.It Bq Er ENOSPC 242The directory in which the entry for the new name is being placed 243cannot be extended because there is no space left on the file 244system containing the directory. 245.It Bq Er EDQUOT 246The directory in which the entry for the new name 247is being placed cannot be extended because the 248user's quota of disk blocks on the file system 249containing the directory has been exhausted. 250.It Bq Er EIO 251An I/O error occurred while making or updating a directory entry. 252.It Bq Er EINTEGRITY 253Corrupted data was detected while reading from the file system. 254.It Bq Er EROFS 255The requested link requires writing in a directory on a read-only file 256system. 257.It Bq Er EFAULT 258Path 259points outside the process's allocated address space. 260.It Bq Er EINVAL 261The 262.Fa from 263argument 264is a parent directory of 265.Fa to , 266or an attempt is made to rename 267.Ql .\& 268or 269.Ql \&.. . 270.It Bq Er EINVAL 271The last component of the 272.Fa to 273path is invalid on the target file system. 274.It Bq Er ENOTEMPTY 275The 276.Fa to 277argument 278is a directory and is not empty. 279.It Bq Er ECAPMODE 280.Fn rename 281was called and the process is in capability mode. 282.El 283.Pp 284In addition to the errors returned by the 285.Fn rename , 286the 287.Fn renameat 288may fail if: 289.Bl -tag -width Er 290.It Bq Er EBADF 291The 292.Fa from 293argument does not specify an absolute path and the 294.Fa fromfd 295argument is neither 296.Dv AT_FDCWD 297nor a valid file descriptor open for searching, or the 298.Fa to 299argument does not specify an absolute path and the 300.Fa tofd 301argument is neither 302.Dv AT_FDCWD 303nor a valid file descriptor open for searching. 304.It Bq Er ENOTDIR 305The 306.Fa from 307argument is not an absolute path and 308.Fa fromfd 309is neither 310.Dv AT_FDCWD 311nor a file descriptor associated with a directory, or the 312.Fa to 313argument is not an absolute path and 314.Fa tofd 315is neither 316.Dv AT_FDCWD 317nor a file descriptor associated with a directory. 318.It Bq Er ECAPMODE 319.Dv AT_FDCWD 320is specified and the process is in capability mode. 321.It Bq Er ENOTCAPABLE 322.Fa path 323is an absolute path or contained a ".." component leading to a directory 324outside of the directory hierarchy specified by 325.Fa fromfd 326or 327.Fa tofd . 328.It Bq Er ENOTCAPABLE 329The 330.Fa fromfd 331file descriptor lacks the 332.Dv CAP_RENAMEAT_SOURCE 333right, or the 334.Fa tofd 335file descriptor lacks the 336.Dv CAP_RENAMEAT_TARGET 337right. 338.El 339.Pp 340In addition to the errors returned by the 341.Fn renameat 342system call, the 343.Fn renameat2 344system call may fail if: 345.Bl -tag -width Er 346.It Bq Er EEXIST 347The 348.Dv AT_RENAME_NOREPLACE 349flag was provided, and a file exists at the path specified by 350.Fa to . 351.It Bq Er EOPNOTSUPP 352One of the 353.Fa flags 354specified is not supported by the filesystem where the to-be 355renamed file is located. 356.El 357.Sh CAVEATS 358If the filesystem which owns the file to be renamed does not 359implement the 360.Dv AT_RENAME_NOREPLACE 361flag, it is possible that due to race with target file creation, 362the error returned by the 363.Fn renameat2 364system call would be non-deterministically either 365.Er EEXIST 366or 367.Er EOPNOTSUPP . 368.Sh SEE ALSO 369.Xr chflags 2 , 370.Xr open 2 , 371.Xr symlink 7 372.Sh STANDARDS 373The 374.Fn rename 375system call is expected to conform to 376.St -p1003.1-96 . 377The 378.Fn renameat 379system call follows The Open Group Extended API Set 2 specification. 380.Sh HISTORY 381The 382.Fn renameat 383system call appeared in 384.Fx 8.0 . 385The 386.Fn renameat2 387system call appeared in 388.Fx 16.0 . 389