1.\" $NetBSD: rename.2,v 1.32 2013/07/28 10:24:59 njoly Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)rename.2 8.1 (Berkeley) 6/4/93 31.\" 32.Dd July 28, 2013 33.Dt RENAME 2 34.Os 35.Sh NAME 36.Nm rename , 37.Nm renameat , 38.Nd change the name of a file 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In stdio.h 43.Ft int 44.Fn rename "const char *from" "const char *to" 45.In unistd.h 46.Ft int 47.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" 48.Sh DESCRIPTION 49.Fn rename 50causes 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 an instance of 66.Fa to 67will always exist, even if the system should crash in 68the middle of the operation. 69.Pp 70If the final component of 71.Fa from 72is a symbolic link, 73the symbolic link is renamed, 74not the file or directory to which it points. 75.Pp 76If both 77.Fa from 78and 79.Fa to 80are pathnames of the same existing file in the file system's name space, 81.Fn rename 82returns successfully and performs no other action. 83.Pp 84.Fn renameat 85works the same way as 86.Fn rename 87except if 88.Fa from 89(resp. 90.Fa to ) 91is relative. 92In that case, it is looked up from a directory whose file 93descriptor was passed as 94.Fa fromfd 95(resp. 96.Fa tofd ) . 97Search permission is required on the directories named by 98.Fa fromfd 99and 100.Fa tofd . 101.\" (These alternatives await a decision about the semantics of O_SEARCH) 102.\" Search permission is required on the directories named by 103.\" .Fa fromfd 104.\" and 105.\" .Fa tofd 106.\" unless they were opened with the 107.\" .Dv O_SEARCH 108.\" flag. 109.\" - or - 110.\" The directories named by 111.\" .Fa fromfd 112.\" and 113.\" .Fa tofd 114.\" must have been opened with the 115.\" .Dv O_SEARCH 116.\" flag. 117.Fa fromfd 118or 119.Fa tofd 120can be set to 121.Dv AT_FDCWD 122in order to specify the current directory. 123.Sh RETURN VALUES 124.Rv -std rename renameat 125.Sh ERRORS 126.Fn rename 127and 128.Fn renameat 129will fail and neither of the argument files will be 130affected if: 131.Bl -tag -width Er 132.It Bq Er EACCES 133A component of either path prefix denies search permission, or 134the requested link requires writing in a directory with a mode 135that denies write permission. 136.It Bq Er EBUSY 137.Fa from 138or 139.Fa to 140is the mount point for a mounted file system. 141.It Bq Er EDQUOT 142The directory in which the entry for the new name 143is being placed cannot be extended because the 144user's quota of disk blocks on the file system 145containing the directory has been exhausted. 146.It Bq Er EFAULT 147.Fa from 148or 149.Fa to 150points outside the process's allocated address space. 151.It Bq Er EINVAL 152.Fa from 153is a parent directory of 154.Fa to , 155or an attempt is made to rename 156.Ql \&. 157or 158.Ql \&.. . 159.It Bq Er EIO 160An I/O error occurred while making or updating a directory entry. 161.It Bq Er EISDIR 162.Fa to 163is a directory, but 164.Fa from 165is not a directory. 166.It Bq Er ELOOP 167Too many symbolic links were encountered in translating either pathname. 168.It Bq Er ENAMETOOLONG 169A component of a pathname exceeded 170.Brq Dv NAME_MAX 171characters, or an entire path name exceeded 172.Brq Dv PATH_MAX 173characters. 174.It Bq Er ENOENT 175A component of the 176.Fa from 177path does not exist, 178or a path prefix of 179.Fa to 180does not exist. 181.It Bq Er ENOSPC 182The directory in which the entry for the new name is being placed 183cannot be extended because there is no space left on the file 184system containing the directory. 185.It Bq Er ENOTDIR 186A component of either path prefix is not a directory, or 187.Fa from 188is a directory, but 189.Fa to 190is not a directory. 191.It Bq Er ENOTEMPTY 192.Fa to 193is a directory and is not empty. 194.It Bq Er EPERM 195The directory containing 196.Fa from 197is marked sticky, 198and neither the containing directory nor 199.Fa from 200are owned by the effective user ID. 201Or the 202.Fa to 203file exists, 204the directory containing 205.Fa to 206is marked sticky, 207and neither the containing directory nor 208.Fa to 209are owned by the effective user ID. 210.It Bq Er EROFS 211The requested link requires writing in a directory on a read-only file 212system. 213.It Bq Er EXDEV 214The link named by 215.Fa to 216and the file named by 217.Fa from 218are on different logical devices (file systems). 219Note that this error code will not be returned if the implementation 220permits cross-device links. 221.El 222.Pp 223In addition, 224.Fn renameat 225will fail if: 226.Bl -tag -width Er 227.It Bq Er EBADF 228.Fa from 229or 230.Fa to 231does not specify an absolute path and 232.Fa fromfd 233or 234.Fa tofd , 235respectively, is neither 236.Dv AT_FDCWD 237nor a valid file descriptor open for reading or searching. 238.It Bq Er ENOTDIR 239.Fa from 240or 241.Fa to 242is not an absolute path and 243.Fa fromfd 244or 245.Fa tofd , 246respectively, is a file descriptor associated with a non-directory file. 247.El 248.Sh SEE ALSO 249.Xr open 2 , 250.Xr symlink 7 251.Sh STANDARDS 252The 253.Fn rename 254function deviates from the semantics defined in 255.St -p1003.1-90 , 256which specifies that if both 257.Fa from 258and 259.Fa to 260.Em link 261to the same existing file, 262.Fn rename 263shall return successfully and performs no further action, whereas this 264implementation will remove the file specified by 265.Fa from 266unless both 267.Fa from 268and 269.Fa to 270are pathnames of the same file in the file system's name space. 271.Pp 272To retain conformance, a compatibility interface is provided by the 273.Lb libposix 274which is also be brought into scope if any of the 275.Dv _POSIX_SOURCE , 276.Dv _POSIX_C_SOURCE 277or 278.Dv _XOPEN_SOURCE 279preprocessor symbols are defined at compile-time: 280the 281.Fn rename 282function conforms to 283.St -p1003.1-90 284and 285.St -xpg4.2 . 286.Fn renameat 287conforms to 288.St -p1003.1-2008 . 289.Sh BUGS 290The system can deadlock if a loop in the file system graph is present. 291This loop takes the form of an entry in directory 292.Ql Pa a , 293say 294.Ql Pa a/foo , 295being a hard link to directory 296.Ql Pa b , 297and an entry in 298directory 299.Ql Pa b , 300say 301.Ql Pa b/bar , 302being a hard link 303to directory 304.Ql Pa a . 305When such a loop exists and two separate processes attempt to 306perform 307.Ql rename a/foo b/bar 308and 309.Ql rename b/bar a/foo , 310respectively, 311the system may deadlock attempting to lock 312both directories for modification. 313Hard links to directories should be 314replaced by symbolic links by the system administrator. 315