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 June 21, 2018 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 EROFS 244The requested link requires writing in a directory on a read-only file 245system. 246.It Bq Er EFAULT 247Path 248points outside the process's allocated address space. 249.It Bq Er EINVAL 250The 251.Fa from 252argument 253is a parent directory of 254.Fa to , 255or an attempt is made to rename 256.Ql .\& 257or 258.Ql \&.. . 259.It Bq Er ENOTEMPTY 260The 261.Fa to 262argument 263is a directory and is not empty. 264.It Bq Er ECAPMODE 265.Fn rename 266was called and the process is in capability mode. 267.El 268.Pp 269In addition to the errors returned by the 270.Fn rename , 271the 272.Fn renameat 273may fail if: 274.Bl -tag -width Er 275.It Bq Er EBADF 276The 277.Fa from 278argument does not specify an absolute path and the 279.Fa fromfd 280argument is neither 281.Dv AT_FDCWD 282nor a valid file descriptor open for searching, or the 283.Fa to 284argument does not specify an absolute path and the 285.Fa tofd 286argument is neither 287.Dv AT_FDCWD 288nor a valid file descriptor open for searching. 289.It Bq Er ENOTDIR 290The 291.Fa from 292argument is not an absolute path and 293.Fa fromfd 294is neither 295.Dv AT_FDCWD 296nor a file descriptor associated with a directory, or the 297.Fa to 298argument is not an absolute path and 299.Fa tofd 300is neither 301.Dv AT_FDCWD 302nor a file descriptor associated with a directory. 303.It Bq Er ECAPMODE 304.Dv AT_FDCWD 305is specified and the process is in capability mode. 306.It Bq Er ENOTCAPABLE 307.Fa path 308is an absolute path or contained a ".." component leading to a directory 309outside of the directory hierarchy specified by 310.Fa fromfd 311or 312.Fa tofd . 313.It Bq Er ENOTCAPABLE 314The 315.Fa fromfd 316file descriptor lacks the 317.Dv CAP_RENAMEAT_SOURCE 318right, or the 319.Fa tofd 320file descriptor lacks the 321.Dv CAP_RENAMEAT_TARGET 322right. 323.El 324.Sh SEE ALSO 325.Xr chflags 2 , 326.Xr open 2 , 327.Xr symlink 7 328.Sh STANDARDS 329The 330.Fn rename 331system call is expected to conform to 332.St -p1003.1-96 . 333The 334.Fn renameat 335system call follows The Open Group Extended API Set 2 specification. 336.Sh HISTORY 337The 338.Fn renameat 339system call appeared in 340.Fx 8.0 . 341