1.\" $OpenBSD: rename.2,v 1.22 2015/09/10 17:55:21 schwarze 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: September 10 2015 $ 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.In stdio.h 42.Ft int 43.Fn rename "const char *from" "const char *to" 44.In fcntl.h 45.In 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 111.Rv -std 112.Sh ERRORS 113.Fn rename 114and 115.Fn renameat 116will fail and neither of the argument files will be 117affected if: 118.Bl -tag -width Er 119.It Bq Er ENAMETOOLONG 120A component of a pathname exceeded 121.Dv NAME_MAX 122characters, or an entire pathname (including the terminating NUL) 123exceeded 124.Dv PATH_MAX 125bytes. 126.It Bq Er ENOENT 127A component of the 128.Fa from 129path does not exist, 130or a path prefix of 131.Fa to 132does not exist. 133.It Bq Er EACCES 134A component of either path prefix denies search permission. 135.It Bq Er EACCES 136The requested change requires writing in a directory that denies write 137permission. 138.It Bq Er EACCES 139The 140.Fa from 141argument is a directory and denies write permission. 142.It Bq Er EPERM 143The directory containing 144.Fa from 145is marked sticky, 146and neither the containing directory nor 147.Fa from 148are owned by the effective user ID. 149.It Bq Er EPERM 150The 151.Fa to 152file exists, 153the directory containing 154.Fa to 155is marked sticky, 156and neither the containing directory nor 157.Fa to 158are owned by the effective user ID. 159.It Bq Er ELOOP 160Too many symbolic links were encountered in translating either pathname. 161.It Bq Er EMLINK 162The link count on the source file or destination directory is at the maximum. 163A rename cannot be completed under these conditions. 164.It Bq Er ENOTDIR 165A component of either path prefix is not a directory. 166.It Bq Er ENOTDIR 167.Fa from 168is a directory, but 169.Fa to 170is not a directory. 171.It Bq Er EISDIR 172.Fa to 173is a directory, but 174.Fa from 175is not a directory. 176.It Bq Er EXDEV 177The link named by 178.Fa to 179and the file named by 180.Fa from 181are on different logical devices (file systems). 182Note that this error code will not be returned if the implementation 183permits cross-device links. 184.It Bq Er ENOSPC 185The directory in which the entry for the new name is being placed 186cannot be extended because there is no space left on the file 187system containing the directory. 188.It Bq Er EDQUOT 189The directory in which the entry for the new name 190is being placed cannot be extended because the 191user's quota of disk blocks on the file system 192containing the directory has been exhausted. 193.It Bq Er EIO 194An I/O error occurred while making or updating a directory entry. 195.It Bq Er EROFS 196The requested link requires writing in a directory on a read-only file 197system. 198.It Bq Er EFAULT 199.Fa from 200or 201.Fa to 202points outside the process's allocated address space. 203.It Bq Er EINVAL 204.Fa from 205is a parent directory of 206.Fa to , 207or an attempt is made to rename 208.Ql \&. 209or 210.Ql \&.. . 211.It Bq Er ENOTEMPTY 212.Fa to 213is a directory and is not empty. 214.El 215.Pp 216Additionally, 217.Fn renameat 218will fail if: 219.Bl -tag -width Er 220.It Bq Er EBADF 221The 222.Fa from 223or 224.Fa to 225argument specifies a relative path and the 226.Fa fromfd 227or 228.Fa tofd 229argument, respectively, is neither 230.Dv AT_FDCWD 231nor a valid file descriptor. 232.It Bq Er ENOTDIR 233The 234.Fa from 235or 236.Fa to 237argument specifies a relative path and the 238.Fa fromfd 239or 240.Fa tofd 241argument, respectively, 242is a valid file descriptor but it does not reference a directory. 243.It Bq Er EACCES 244The 245.Fa from 246or 247.Fa to 248argument specifies a relative path but search permission is denied 249for the directory which the 250.Fa fromfd 251or 252.Fa tofd 253file descriptor, respectively, references. 254.El 255.Sh SEE ALSO 256.Xr mv 1 , 257.Xr open 2 , 258.Xr symlink 7 259.Sh STANDARDS 260The 261.Fn rename 262and 263.Fn renameat 264functions conform to 265.St -p1003.1-2008 . 266.Sh HISTORY 267The 268.Fn renameat 269function appeared in 270.Ox 5.0 . 271.Sh CAVEATS 272The system can deadlock if a loop in the file system graph is present. 273This loop takes the form of an entry in directory 274.Sq Pa a , 275say 276.Sq Pa a/foo , 277being a hard link to directory 278.Sq Pa b , 279and an entry in 280directory 281.Sq Pa b , 282say 283.Sq Pa b/bar , 284being a hard link 285to directory 286.Sq Pa a . 287When such a loop exists and two separate processes attempt to 288perform 289.Ql rename a/foo b/bar 290and 291.Ql rename b/bar a/foo , 292respectively, 293the system may deadlock attempting to lock 294both directories for modification. 295Hard links to directories should be 296replaced by symbolic links by the system administrator. 297