1.\" $NetBSD: rename.2,v 1.27 2013/01/13 08:15:02 dholland 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 November 18, 2012 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.Ft int 46.Fn rename "int fromfd" "const char *from" "int tofd" "const char *to" 47.Sh DESCRIPTION 48.Fn rename 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 63.Fn rename 64guarantees that an instance of 65.Fa to 66will always exist, even if the system should crash in 67the middle of the operation. 68.Pp 69If the final component of 70.Fa from 71is a symbolic link, 72the symbolic link is renamed, 73not the file or directory to which it points. 74.Pp 75If both 76.Fa from 77and 78.Fa to 79are pathnames of the same existing file in the file system's name space, 80.Fn rename 81returns successfully and performs no other action. 82.Pp 83.Fn renameat 84works the same way as 85.Fn rename 86except if 87.Fa from 88(resp. 89.Fa to ) 90is relative. 91In that case, it is looked up from a directory whose file 92descriptor was passed as 93.Fa fromfd 94(resp. 95.Fa tofd ). 96Search permission is required on the directories named by 97.Fa fromfd 98and 99.Fa tofd. 100.\" (These alternatives await a decision about the semantics of O_SEARCH) 101.\" Search permission is required on the directories named by 102.\" .Fa fromfd 103.\" and 104.\" .Fa tofd 105.\" unless they were opened with the 106.\" .Dv O_SEARCH 107.\" flag. 108.\" - or - 109.\" The directories named by 110.\" .Fa fromfd 111.\" and 112.\" .Fa tofd 113.\" must have been opened with the 114.\" .Dv O_SEARCH 115.\" flag. 116.Fa fromfd 117or 118.Fa tofd 119can be set to 120.Dv AT_FDCWD 121in order to specify the current directory. 122.Sh RETURN VALUES 123A 0 value is returned if the operation succeeds, otherwise 124.Fn rename 125returns \-1 and the global variable 126.Va errno 127indicates the reason for the failure. 128.Sh ERRORS 129.Fn rename 130will fail and neither of the argument files will be 131affected if: 132.Bl -tag -width Er 133.It Bq Er ENAMETOOLONG 134A component of a pathname exceeded 135.Brq Dv NAME_MAX 136characters, or an entire path name exceeded 137.Brq Dv PATH_MAX 138characters. 139.It Bq Er ENOENT 140A component of the 141.Fa from 142path does not exist, 143or a path prefix of 144.Fa to 145does not exist. 146.It Bq Er EACCES 147A component of either path prefix denies search permission, or 148the requested link requires writing in a directory with a mode 149that denies write permission. 150.It Bq Er EPERM 151The directory containing 152.Fa from 153is marked sticky, 154and neither the containing directory nor 155.Fa from 156are owned by the effective user ID. 157Or the 158.Fa to 159file exists, 160the directory containing 161.Fa to 162is marked sticky, 163and neither the containing directory nor 164.Fa to 165are owned by the effective user ID. 166.It Bq Er ELOOP 167Too many symbolic links were encountered in translating either pathname. 168.It Bq Er ENOTDIR 169A component of either path prefix is not a directory, or 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.Em Path 203points outside the process's allocated address space. 204.It Bq Er EINVAL 205.Fa from 206is a parent directory of 207.Fa to , 208or an attempt is made to rename 209.Ql \&. 210or 211.Ql \&.. . 212.It Bq Er ENOTEMPTY 213.Fa to 214is a directory and is not empty. 215.It Bq Er EBUSY 216.Fa from 217or 218.Fa to 219is the mount point for a mounted file system. 220.El 221.Sh SEE ALSO 222.Xr open 2 , 223.Xr symlink 7 224.Sh STANDARDS 225The 226.Fn rename 227function deviates from the semantics defined in 228.St -p1003.1-90 , 229which specifies that if both 230.Fa from 231and 232.Fa to 233.Em link 234to the same existing file, 235.Fn rename 236shall return successfully and performs no further action, whereas this 237implementation will remove the file specified by 238.Fa from 239unless both 240.Fa from 241and 242.Fa to 243are pathnames of the same file in the file system's name space. 244.Pp 245To retain conformance, a compatibility interface is provided by the 246.Lb libposix 247which is also be brought into scope if any of the 248.Dv _POSIX_SOURCE , 249.Dv _POSIX_C_SOURCE 250or 251.Dv _XOPEN_SOURCE 252preprocessor symbols are defined at compile-time: 253the 254.Fn rename 255function conforms to 256.St -p1003.1-90 257and 258.St -xpg4.2 . 259.Fn renameat 260conforms to 261.St -p1003.1-2008 . 262.Sh BUGS 263The system can deadlock if a loop in the file system graph is present. 264This loop takes the form of an entry in directory 265.Ql Pa a , 266say 267.Ql Pa a/foo , 268being a hard link to directory 269.Ql Pa b , 270and an entry in 271directory 272.Ql Pa b , 273say 274.Ql Pa b/bar , 275being a hard link 276to directory 277.Ql Pa a . 278When such a loop exists and two separate processes attempt to 279perform 280.Ql rename a/foo b/bar 281and 282.Ql rename b/bar a/foo , 283respectively, 284the system may deadlock attempting to lock 285both directories for modification. 286Hard links to directories should be 287replaced by symbolic links by the system administrator. 288