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