1.\" $OpenBSD: rename.2,v 1.16 2011/07/19 07:06:22 jmc 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: July 19 2011 $ 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 <fcntl.h> 42.Fd #include <stdio.h> 43.Ft int 44.Fn rename "const char *from" "const char *to" 45.Ft int 46.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" 47.Sh DESCRIPTION 48The 49.Fn rename 50function causes the link named 51.Fa from 52to be renamed as 53.Fa to . 54If 55.Fa to 56exists, it is first removed. 57Both 58.Fa from 59and 60.Fa to 61must be of the same type (that is, both directories or both 62non-directories), and must reside on the same file system. 63.Pp 64.Fn rename 65guarantees that if 66.Fa to 67already exists, an instance of 68.Fa to 69will always exist, even if the system should crash in 70the middle of the operation. 71.Pp 72If the final component of 73.Fa from 74is a symbolic link, 75the symbolic link is renamed, 76not the file or directory to which it points. 77.Pp 78The 79.Fn renameat 80function is equivalent to 81.Fn rename 82except that where 83.Fa from 84or 85.Fa to 86specifies a relative path, 87the directory entry names used are resolved relative to 88the directories associated with file descriptors 89.Fa fromfd 90or 91.Fa tofd 92(respectively) instead of the current working directory. 93.Pp 94If 95.Fn renameat 96is passed the special value 97.Dv AT_FDCWD 98(defined in 99.In fcntl.h ) 100in the 101.Fa fromfd 102or 103.Fa tofd 104parameter, the current working directory is used for resolving the respective 105.Fa from 106or 107.Fa to 108argument. 109.Sh RETURN VALUES 110A 0 value is returned if the operation succeeds, otherwise 111.Fn rename 112returns \-1 and the global variable 113.Va errno 114indicates the reason for the failure. 115.Sh ERRORS 116.Fn rename 117and 118.Fn renameat 119will fail and neither of the argument files will be 120affected if: 121.Bl -tag -width Er 122.It Bq Er ENAMETOOLONG 123A component of a pathname exceeded 124.Dv {NAME_MAX} 125characters, or an entire path name exceeded 126.Dv {PATH_MAX} 127characters. 128.It Bq Er ENOENT 129A component of the 130.Fa from 131path does not exist, 132or a path prefix of 133.Fa to 134does not exist. 135.It Bq Er EACCES 136A component of either path prefix denies search permission. 137.It Bq Er EACCES 138The requested link requires writing in a directory with a mode 139that denies write permission. 140.It Bq Er EPERM 141The directory containing 142.Fa from 143is marked sticky, 144and neither the containing directory nor 145.Fa from 146are owned by the effective user ID. 147.It Bq Er EPERM 148The 149.Fa to 150file exists, 151the directory containing 152.Fa to 153is marked sticky, 154and neither the containing directory nor 155.Fa to 156are owned by the effective user ID. 157.It Bq Er ELOOP 158Too many symbolic links were encountered in translating either pathname. 159.It Bq Er EMLINK 160The link count on the source file or destination directory is at the maximum. 161A rename cannot be completed under these conditions. 162.It Bq Er ENOTDIR 163A component of either path prefix is not a directory. 164.It Bq Er ENOTDIR 165.Fa from 166is a directory, but 167.Fa to 168is not a directory. 169.It Bq Er EISDIR 170.Fa to 171is a directory, but 172.Fa from 173is not a directory. 174.It Bq Er EXDEV 175The link named by 176.Fa to 177and the file named by 178.Fa from 179are on different logical devices (file systems). 180Note that this error code will not be returned if the implementation 181permits cross-device links. 182.It Bq Er ENOSPC 183The directory in which the entry for the new name is being placed 184cannot be extended because there is no space left on the file 185system containing the directory. 186.It Bq Er EDQUOT 187The directory in which the entry for the new name 188is being placed cannot be extended because the 189user's quota of disk blocks on the file system 190containing the directory has been exhausted. 191.It Bq Er EIO 192An I/O error occurred while making or updating a directory entry. 193.It Bq Er EROFS 194The requested link requires writing in a directory on a read-only file 195system. 196.It Bq Er EFAULT 197.Fa from 198or 199.Fa to 200points outside the process's allocated address space. 201.It Bq Er EINVAL 202.Fa from 203is a parent directory of 204.Fa to , 205or an attempt is made to rename 206.Ql \&. 207or 208.Ql \&.. . 209.It Bq Er ENOTEMPTY 210.Fa to 211is a directory and is not empty. 212.El 213.Pp 214Additionally, 215.Fn renameat 216will fail if: 217.Bl -tag -width Er 218.It Bq Er EBADF 219The 220.Fa from 221or 222.Fa to 223argument does not specify an absolute path and 224.Fa fromfd 225or 226.Fa tofd , 227respectively, is neither 228.Dv AT_FDCWD 229nor a valid file descriptor open for reading. 230.El 231.Sh SEE ALSO 232.Xr mv 1 , 233.Xr open 2 , 234.Xr symlink 7 235.Sh STANDARDS 236The 237.Fn rename 238and 239.Fn renameat 240functions conform to 241.St -p1003.1-2008 . 242.Sh HISTORY 243The 244.Fn renameat 245function appeared in 246.Ox 5.0 . 247.Sh CAVEATS 248The system can deadlock if a loop in the file system graph is present. 249This loop takes the form of an entry in directory 250.Sq Pa a , 251say 252.Sq Pa a/foo , 253being a hard link to directory 254.Sq Pa b , 255and an entry in 256directory 257.Sq Pa b , 258say 259.Sq Pa b/bar , 260being a hard link 261to directory 262.Sq Pa a . 263When such a loop exists and two separate processes attempt to 264perform 265.Ql rename a/foo b/bar 266and 267.Ql rename b/bar a/foo , 268respectively, 269the system may deadlock attempting to lock 270both directories for modification. 271Hard links to directories should be 272replaced by symbolic links by the system administrator. 273