1.\" $OpenBSD: rename.2,v 1.19 2013/05/08 16:13:12 tedu Exp $ 2.\" $NetBSD: rename.2,v 1.7 1995/02/27 12:36:15 cgd Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)rename.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: May 8 2013 $ 34.Dt RENAME 2 35.Os 36.Sh NAME 37.Nm rename , 38.Nm renameat 39.Nd change the name of a file 40.Sh SYNOPSIS 41.Fd #include <stdio.h> 42.Ft int 43.Fn rename "const char *from" "const char *to" 44.Fd #include <fcntl.h> 45.Fd #include <stdio.h> 46.Ft int 47.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" 48.Sh DESCRIPTION 49The 50.Fn rename 51function causes the link named 52.Fa from 53to be renamed as 54.Fa to . 55If 56.Fa to 57exists, it is first removed. 58Both 59.Fa from 60and 61.Fa to 62must be of the same type (that is, both directories or both 63non-directories), and must reside on the same file system. 64.Pp 65.Fn rename 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 79The 80.Fn renameat 81function is equivalent to 82.Fn rename 83except that where 84.Fa from 85or 86.Fa to 87specifies a relative path, 88the directory entry names used are resolved relative to 89the directories associated with file descriptors 90.Fa fromfd 91or 92.Fa tofd 93(respectively) instead of the current working directory. 94.Pp 95If 96.Fn renameat 97is passed the special value 98.Dv AT_FDCWD 99(defined in 100.In fcntl.h ) 101in the 102.Fa fromfd 103or 104.Fa tofd 105parameter, the current working directory is used for resolving the respective 106.Fa from 107or 108.Fa to 109argument. 110.Sh RETURN VALUES 111A 0 value is returned if the operation succeeds, otherwise 112.Fn rename 113returns \-1 and the global variable 114.Va errno 115indicates the reason for the failure. 116.Sh ERRORS 117.Fn rename 118and 119.Fn renameat 120will fail and neither of the argument files will be 121affected if: 122.Bl -tag -width Er 123.It Bq Er ENAMETOOLONG 124A component of a pathname exceeded 125.Dv {NAME_MAX} 126characters, or an entire path name exceeded 127.Dv {PATH_MAX} 128characters. 129.It Bq Er ENOENT 130A component of the 131.Fa from 132path does not exist, 133or a path prefix of 134.Fa to 135does not exist. 136.It Bq Er EACCES 137A component of either path prefix denies search permission. 138.It Bq Er EACCES 139The requested change requires writing in a directory that denies write 140permission. 141.It Bq Er EACCES 142The 143.Fa from 144argument is a directory and denies write permission. 145.It Bq Er EPERM 146The directory containing 147.Fa from 148is marked sticky, 149and neither the containing directory nor 150.Fa from 151are owned by the effective user ID. 152.It Bq Er EPERM 153The 154.Fa to 155file exists, 156the directory containing 157.Fa to 158is marked sticky, 159and neither the containing directory nor 160.Fa to 161are owned by the effective user ID. 162.It Bq Er ELOOP 163Too many symbolic links were encountered in translating either pathname. 164.It Bq Er EMLINK 165The link count on the source file or destination directory is at the maximum. 166A rename cannot be completed under these conditions. 167.It Bq Er ENOTDIR 168A component of either path prefix is not a directory. 169.It Bq Er ENOTDIR 170.Fa from 171is a directory, but 172.Fa to 173is not a directory. 174.It Bq Er EISDIR 175.Fa to 176is a directory, but 177.Fa from 178is not a directory. 179.It Bq Er EXDEV 180The link named by 181.Fa to 182and the file named by 183.Fa from 184are on different logical devices (file systems). 185Note that this error code will not be returned if the implementation 186permits cross-device links. 187.It Bq Er ENOSPC 188The directory in which the entry for the new name is being placed 189cannot be extended because there is no space left on the file 190system containing the directory. 191.It Bq Er EDQUOT 192The directory in which the entry for the new name 193is being placed cannot be extended because the 194user's quota of disk blocks on the file system 195containing the directory has been exhausted. 196.It Bq Er EIO 197An I/O error occurred while making or updating a directory entry. 198.It Bq Er EROFS 199The requested link requires writing in a directory on a read-only file 200system. 201.It Bq Er EFAULT 202.Fa from 203or 204.Fa to 205points outside the process's allocated address space. 206.It Bq Er EINVAL 207.Fa from 208is a parent directory of 209.Fa to , 210or an attempt is made to rename 211.Ql \&. 212or 213.Ql \&.. . 214.It Bq Er ENOTEMPTY 215.Fa to 216is a directory and is not empty. 217.El 218.Pp 219Additionally, 220.Fn renameat 221will fail if: 222.Bl -tag -width Er 223.It Bq Er EBADF 224The 225.Fa from 226or 227.Fa to 228argument specifies a relative path and the 229.Fa fromfd 230or 231.Fa tofd 232argument, respectively, is neither 233.Dv AT_FDCWD 234nor a valid file descriptor. 235.It Bq Er ENOTDIR 236The 237.Fa from 238or 239.Fa to 240argument specifies a relative path and the 241.Fa fromfd 242or 243.Fa tofd 244argument, respectively, 245is a valid file descriptor but it does not reference a directory. 246.It Bq Er EACCES 247The 248.Fa from 249or 250.Fa to 251argument specifies a relative path but search permission is denied 252for the directory which the 253.Fa fromfd 254or 255.Fa tofd 256file descriptor, respectively, references. 257.El 258.Sh SEE ALSO 259.Xr mv 1 , 260.Xr open 2 , 261.Xr symlink 7 262.Sh STANDARDS 263The 264.Fn rename 265and 266.Fn renameat 267functions conform to 268.St -p1003.1-2008 . 269.Sh HISTORY 270The 271.Fn renameat 272function appeared in 273.Ox 5.0 . 274.Sh CAVEATS 275The system can deadlock if a loop in the file system graph is present. 276This loop takes the form of an entry in directory 277.Sq Pa a , 278say 279.Sq Pa a/foo , 280being a hard link to directory 281.Sq Pa b , 282and an entry in 283directory 284.Sq Pa b , 285say 286.Sq Pa b/bar , 287being a hard link 288to directory 289.Sq Pa a . 290When such a loop exists and two separate processes attempt to 291perform 292.Ql rename a/foo b/bar 293and 294.Ql rename b/bar a/foo , 295respectively, 296the system may deadlock attempting to lock 297both directories for modification. 298Hard links to directories should be 299replaced by symbolic links by the system administrator. 300