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.\" @(#)rename.2 8.1 (Berkeley) 6/4/93 29.\" 30.Dd March 30, 2020 31.Dt RENAME 2 32.Os 33.Sh NAME 34.Nm rename 35.Nd change the name of a file 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In stdio.h 40.Ft int 41.Fn rename "const char *from" "const char *to" 42.Ft int 43.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" 44.Sh DESCRIPTION 45The 46.Fn rename 47system call 48causes the link named 49.Fa from 50to be renamed as 51.Fa to . 52If 53.Fa to 54exists, it is first removed. 55Both 56.Fa from 57and 58.Fa to 59must be of the same type (that is, both directories or both 60non-directories), and must reside on the same file system. 61.Pp 62The 63.Fn rename 64system call 65guarantees that if 66.Fa to 67already exists, an instance of 68.Fa to 69will always exist, even if the system should crash in 70the middle of the operation. 71.Pp 72If the final component of 73.Fa from 74is a symbolic link, 75the symbolic link is renamed, 76not the file or directory to which it points. 77.Pp 78If 79.Fa from 80and 81.Fa to 82resolve to the same directory entry, or to different directory 83entries for the same existing file, 84.Fn rename 85returns success without taking any further action. 86.Pp 87The 88.Fn renameat 89system call is equivalent to 90.Fn rename 91except in the case where either 92.Fa from 93or 94.Fa to 95specifies a relative path. 96If 97.Fa from 98is a relative path, the file to be renamed is located 99relative to the directory associated with the file descriptor 100.Fa fromfd 101instead of the current working directory. 102If the 103.Fa to 104is a relative path, the same happens only relative to the directory associated 105with 106.Fa tofd . 107If the 108.Fn renameat 109is passed the special value 110.Dv AT_FDCWD 111in the 112.Fa fromfd 113or 114.Fa tofd 115parameter, the current working directory is used in the determination 116of the file for the respective path parameter. 117.\".Sh CAVEAT 118.\"The system can deadlock if a loop in the file system graph is present. 119.\"This loop takes the form of an entry in directory 120.\".Pa a , 121.\"say 122.\".Pa a/foo , 123.\"being a hard link to directory 124.\".Pa b , 125.\"and an entry in 126.\"directory 127.\".Pa b , 128.\"say 129.\".Pa b/bar , 130.\"being a hard link 131.\"to directory 132.\".Pa a . 133.\"When such a loop exists and two separate processes attempt to 134.\"perform 135.\".Ql rename a/foo b/bar 136.\"and 137.\".Ql rename b/bar a/foo , 138.\"respectively, 139.\"the system may deadlock attempting to lock 140.\"both directories for modification. 141.\"Hard links to directories should be 142.\"replaced by symbolic links by the system administrator. 143.Sh RETURN VALUES 144.Rv -std rename 145.Sh ERRORS 146The 147.Fn rename 148system call 149will fail and neither of the argument files will be 150affected if: 151.Bl -tag -width Er 152.It Bq Er ENAMETOOLONG 153A component of either pathname exceeded 255 characters, 154or the entire length of either path name exceeded 1023 characters. 155.It Bq Er ENOENT 156A component of the 157.Fa from 158path does not exist, 159or a path prefix of 160.Fa to 161does not exist. 162.It Bq Er EACCES 163A component of either path prefix denies search permission. 164.It Bq Er EACCES 165The requested link requires writing in a directory with a mode 166that denies write permission. 167.It Bq Er EACCES 168The directory pointed at by the 169.Fa from 170argument denies write permission, and the operation would move 171it to another parent directory. 172.It Bq Er EPERM 173The file pointed at by the 174.Fa from 175argument has its immutable, undeletable or append-only flag set, see the 176.Xr chflags 2 177manual page for more information. 178.It Bq Er EPERM 179The parent directory of the file pointed at by the 180.Fa from 181argument has its immutable or append-only flag set. 182.It Bq Er EPERM 183The parent directory of the file pointed at by the 184.Fa to 185argument has its immutable flag set. 186.It Bq Er EPERM 187The directory containing 188.Fa from 189is marked sticky, 190and neither the containing directory nor 191.Fa from 192are owned by the effective user ID. 193.It Bq Er EPERM 194The file pointed at by the 195.Fa to 196argument 197exists, 198the directory containing 199.Fa to 200is marked sticky, 201and neither the containing directory nor 202.Fa to 203are owned by the effective user ID. 204.It Bq Er ELOOP 205Too many symbolic links were encountered in translating either pathname. 206.It Bq Er ENOTDIR 207A component of either path prefix is not a directory. 208.It Bq Er ENOTDIR 209The 210.Fa from 211argument 212is a directory, but 213.Fa to 214is not a directory. 215.It Bq Er EISDIR 216The 217.Fa to 218argument 219is a directory, but 220.Fa from 221is not a directory. 222.It Bq Er EXDEV 223The link named by 224.Fa to 225and the file named by 226.Fa from 227are on different logical devices (file systems). 228Note that this error 229code will not be returned if the implementation permits cross-device 230links. 231.It Bq Er ENOSPC 232The directory in which the entry for the new name is being placed 233cannot be extended because there is no space left on the file 234system containing the directory. 235.It Bq Er EDQUOT 236The directory in which the entry for the new name 237is being placed cannot be extended because the 238user's quota of disk blocks on the file system 239containing the directory has been exhausted. 240.It Bq Er EIO 241An I/O error occurred while making or updating a directory entry. 242.It Bq Er EINTEGRITY 243Corrupted data was detected while reading from the file system. 244.It Bq Er EROFS 245The requested link requires writing in a directory on a read-only file 246system. 247.It Bq Er EFAULT 248Path 249points outside the process's allocated address space. 250.It Bq Er EINVAL 251The 252.Fa from 253argument 254is a parent directory of 255.Fa to , 256or an attempt is made to rename 257.Ql .\& 258or 259.Ql \&.. . 260.It Bq Er ENOTEMPTY 261The 262.Fa to 263argument 264is a directory and is not empty. 265.It Bq Er ECAPMODE 266.Fn rename 267was called and the process is in capability mode. 268.El 269.Pp 270In addition to the errors returned by the 271.Fn rename , 272the 273.Fn renameat 274may fail if: 275.Bl -tag -width Er 276.It Bq Er EBADF 277The 278.Fa from 279argument does not specify an absolute path and the 280.Fa fromfd 281argument is neither 282.Dv AT_FDCWD 283nor a valid file descriptor open for searching, or the 284.Fa to 285argument does not specify an absolute path and the 286.Fa tofd 287argument is neither 288.Dv AT_FDCWD 289nor a valid file descriptor open for searching. 290.It Bq Er ENOTDIR 291The 292.Fa from 293argument is not an absolute path and 294.Fa fromfd 295is neither 296.Dv AT_FDCWD 297nor a file descriptor associated with a directory, or the 298.Fa to 299argument is not an absolute path and 300.Fa tofd 301is neither 302.Dv AT_FDCWD 303nor a file descriptor associated with a directory. 304.It Bq Er ECAPMODE 305.Dv AT_FDCWD 306is specified and the process is in capability mode. 307.It Bq Er ENOTCAPABLE 308.Fa path 309is an absolute path or contained a ".." component leading to a directory 310outside of the directory hierarchy specified by 311.Fa fromfd 312or 313.Fa tofd . 314.It Bq Er ENOTCAPABLE 315The 316.Fa fromfd 317file descriptor lacks the 318.Dv CAP_RENAMEAT_SOURCE 319right, or the 320.Fa tofd 321file descriptor lacks the 322.Dv CAP_RENAMEAT_TARGET 323right. 324.El 325.Sh SEE ALSO 326.Xr chflags 2 , 327.Xr open 2 , 328.Xr symlink 7 329.Sh STANDARDS 330The 331.Fn rename 332system call is expected to conform to 333.St -p1003.1-96 . 334The 335.Fn renameat 336system call follows The Open Group Extended API Set 2 specification. 337.Sh HISTORY 338The 339.Fn renameat 340system call appeared in 341.Fx 8.0 . 342