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.El 147.Sh RETURN VALUES 148.Rv -std rename 149.Sh ERRORS 150The 151.Fn rename 152system call 153will fail and neither of the argument files will be 154affected if: 155.Bl -tag -width Er 156.It Bq Er ENAMETOOLONG 157A component of either pathname exceeded 255 characters, 158or the entire length of either path name exceeded 1023 characters. 159.It Bq Er ENOENT 160A component of the 161.Fa from 162path does not exist, 163or a path prefix of 164.Fa to 165does not exist. 166.It Bq Er EACCES 167A component of either path prefix denies search permission. 168.It Bq Er EACCES 169The requested link requires writing in a directory with a mode 170that denies write permission. 171.It Bq Er EACCES 172The directory pointed at by the 173.Fa from 174argument denies write permission, and the operation would move 175it to another parent directory. 176.It Bq Er EPERM 177The file pointed at by the 178.Fa from 179argument has its immutable, undeletable or append-only flag set, see the 180.Xr chflags 2 181manual page for more information. 182.It Bq Er EPERM 183The parent directory of the file pointed at by the 184.Fa from 185argument has its immutable or append-only flag set. 186.It Bq Er EPERM 187The parent directory of the file pointed at by the 188.Fa to 189argument has its immutable flag set. 190.It Bq Er EPERM 191The directory containing 192.Fa from 193is marked sticky, 194and neither the containing directory nor 195.Fa from 196are owned by the effective user ID. 197.It Bq Er EPERM 198The file pointed at by the 199.Fa to 200argument 201exists, 202the directory containing 203.Fa to 204is marked sticky, 205and neither the containing directory nor 206.Fa to 207are owned by the effective user ID. 208.It Bq Er ELOOP 209Too many symbolic links were encountered in translating either pathname. 210.It Bq Er ENOTDIR 211A component of either path prefix is not a directory. 212.It Bq Er ENOTDIR 213The 214.Fa from 215argument 216is a directory, but 217.Fa to 218is not a directory. 219.It Bq Er EISDIR 220The 221.Fa to 222argument 223is a directory, but 224.Fa from 225is not a directory. 226.It Bq Er EXDEV 227The link named by 228.Fa to 229and the file named by 230.Fa from 231are on different logical devices (file systems). 232Note that this error 233code will not be returned if the implementation permits cross-device 234links. 235.It Bq Er ENOSPC 236The directory in which the entry for the new name is being placed 237cannot be extended because there is no space left on the file 238system containing the directory. 239.It Bq Er EDQUOT 240The directory in which the entry for the new name 241is being placed cannot be extended because the 242user's quota of disk blocks on the file system 243containing the directory has been exhausted. 244.It Bq Er EIO 245An I/O error occurred while making or updating a directory entry. 246.It Bq Er EINTEGRITY 247Corrupted data was detected while reading from the file system. 248.It Bq Er EROFS 249The requested link requires writing in a directory on a read-only file 250system. 251.It Bq Er EFAULT 252Path 253points outside the process's allocated address space. 254.It Bq Er EINVAL 255The 256.Fa from 257argument 258is a parent directory of 259.Fa to , 260or an attempt is made to rename 261.Ql .\& 262or 263.Ql \&.. . 264.It Bq Er EINVAL 265The last component of the 266.Fa to 267path is invalid on the target file system. 268.It Bq Er ENOTEMPTY 269The 270.Fa to 271argument 272is a directory and is not empty. 273.It Bq Er ECAPMODE 274.Fn rename 275was called and the process is in capability mode. 276.El 277.Pp 278In addition to the errors returned by the 279.Fn rename , 280the 281.Fn renameat 282may fail if: 283.Bl -tag -width Er 284.It Bq Er EBADF 285The 286.Fa from 287argument does not specify an absolute path and the 288.Fa fromfd 289argument is neither 290.Dv AT_FDCWD 291nor a valid file descriptor open for searching, or the 292.Fa to 293argument does not specify an absolute path and the 294.Fa tofd 295argument is neither 296.Dv AT_FDCWD 297nor a valid file descriptor open for searching. 298.It Bq Er ENOTDIR 299The 300.Fa from 301argument is not an absolute path and 302.Fa fromfd 303is neither 304.Dv AT_FDCWD 305nor a file descriptor associated with a directory, or the 306.Fa to 307argument is not an absolute path and 308.Fa tofd 309is neither 310.Dv AT_FDCWD 311nor a file descriptor associated with a directory. 312.It Bq Er ECAPMODE 313.Dv AT_FDCWD 314is specified and the process is in capability mode. 315.It Bq Er ENOTCAPABLE 316.Fa path 317is an absolute path or contained a ".." component leading to a directory 318outside of the directory hierarchy specified by 319.Fa fromfd 320or 321.Fa tofd . 322.It Bq Er ENOTCAPABLE 323The 324.Fa fromfd 325file descriptor lacks the 326.Dv CAP_RENAMEAT_SOURCE 327right, or the 328.Fa tofd 329file descriptor lacks the 330.Dv CAP_RENAMEAT_TARGET 331right. 332.El 333.Pp 334In addition to the errors returned by the 335.Fn renameat 336system call, the 337.Fn renameat2 338system call may fail if: 339.Bl -tag -width Er 340.It Bq Er EEXIST 341The 342.Dv AT_RENAME_NOREPLACE 343flag was provided, and a file exists at the path specified by 344.Fa to . 345.It Bq Er EOPNOTSUPP 346One of the 347.Fa flags 348specified is not supported by the filesystem where the to-be 349renamed file is located. 350.El 351.Sh CAVEATS 352If the filesystem which owns the file to be renamed does not 353implement the 354.Dv AT_RENAME_NOREPLACE 355flag, it is possible that due to race with target file creation, 356the error returned by the 357.Fn renameat2 358system call would be non-deterministically either 359.Er EEXIST 360or 361.Er EOPNOTSUPP . 362.Sh SEE ALSO 363.Xr chflags 2 , 364.Xr open 2 , 365.Xr symlink 7 366.Sh STANDARDS 367The 368.Fn rename 369system call is expected to conform to 370.St -p1003.1-96 . 371The 372.Fn renameat 373system call follows The Open Group Extended API Set 2 specification. 374.Sh HISTORY 375The 376.Fn renameat 377system call appeared in 378.Fx 8.0 . 379The 380.Fn renameat2 381system call appeared in 382.Fx 16.0 . 383