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