1.\" $NetBSD: rename.2,v 1.23 2010/05/31 12:16:20 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 December 27, 2005 33.Dt RENAME 2 34.Os 35.Sh NAME 36.Nm rename 37.Nd change the name of a file 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In stdio.h 42.Ft int 43.Fn rename "const char *from" "const char *to" 44.Sh DESCRIPTION 45.Fn rename 46causes the link named 47.Fa from 48to be renamed as 49.Fa to . 50If 51.Fa to 52exists, it is first removed. 53Both 54.Fa from 55and 56.Fa to 57must be of the same type (that is, both directories or both 58non-directories), and must reside on the same file system. 59.Pp 60.Fn rename 61guarantees that an instance of 62.Fa to 63will always exist, even if the system should crash in 64the middle of the operation. 65.Pp 66If the final component of 67.Fa from 68is a symbolic link, 69the symbolic link is renamed, 70not the file or directory to which it points. 71.Pp 72If both 73.Fa from 74and 75.Fa to 76are pathnames of the same existing file in the file system's name space, 77.Fn rename 78returns successfully and performs no other action. 79.Sh RETURN VALUES 80A 0 value is returned if the operation succeeds, otherwise 81.Fn rename 82returns \-1 and the global variable 83.Va errno 84indicates the reason for the failure. 85.Sh ERRORS 86.Fn rename 87will fail and neither of the argument files will be 88affected if: 89.Bl -tag -width Er 90.It Bq Er ENAMETOOLONG 91A component of a pathname exceeded 92.Brq Dv NAME_MAX 93characters, or an entire path name exceeded 94.Brq Dv PATH_MAX 95characters. 96.It Bq Er ENOENT 97A component of the 98.Fa from 99path does not exist, 100or a path prefix of 101.Fa to 102does not exist. 103.It Bq Er EACCES 104A component of either path prefix denies search permission, or 105the requested link requires writing in a directory with a mode 106that denies write permission. 107.It Bq Er EPERM 108The directory containing 109.Fa from 110is marked sticky, 111and neither the containing directory nor 112.Fa from 113are owned by the effective user ID. 114Or the 115.Fa to 116file exists, 117the directory containing 118.Fa to 119is marked sticky, 120and neither the containing directory nor 121.Fa to 122are owned by the effective user ID. 123.It Bq Er ELOOP 124Too many symbolic links were encountered in translating either pathname. 125.It Bq Er ENOTDIR 126A component of either path prefix is not a directory, or 127.Fa from 128is a directory, but 129.Fa to 130is not a directory. 131.It Bq Er EISDIR 132.Fa to 133is a directory, but 134.Fa from 135is not a directory. 136.It Bq Er EXDEV 137The link named by 138.Fa to 139and the file named by 140.Fa from 141are on different logical devices (file systems). 142Note that this error code will not be returned if the implementation 143permits cross-device links. 144.It Bq Er ENOSPC 145The directory in which the entry for the new name is being placed 146cannot be extended because there is no space left on the file 147system containing the directory. 148.It Bq Er EDQUOT 149The directory in which the entry for the new name 150is being placed cannot be extended because the 151user's quota of disk blocks on the file system 152containing the directory has been exhausted. 153.It Bq Er EIO 154An I/O error occurred while making or updating a directory entry. 155.It Bq Er EROFS 156The requested link requires writing in a directory on a read-only file 157system. 158.It Bq Er EFAULT 159.Em Path 160points outside the process's allocated address space. 161.It Bq Er EINVAL 162.Fa from 163is a parent directory of 164.Fa to , 165or an attempt is made to rename 166.Ql \&. 167or 168.Ql \&.. . 169.It Bq Er ENOTEMPTY 170.Fa to 171is a directory and is not empty. 172.It Bq Er EBUSY 173.Fa from 174or 175.Fa to 176is the mount point for a mounted file system. 177.El 178.Sh SEE ALSO 179.Xr open 2 , 180.Xr symlink 7 181.Sh STANDARDS 182The 183.Fn rename 184function deviates from the semantics defined in 185.St -p1003.1-90 , 186which specifies that if both 187.Fa from 188and 189.Fa to 190.Em link 191to the same existing file, 192.Fn rename 193shall return successfully and performs no further action, whereas this 194implementation will remove the file specified by 195.Fa from 196unless both 197.Fa from 198and 199.Fa to 200are pathnames of the same file in the file system's name space. 201.Pp 202To retain conformance, a compatibility interface is provided by the 203.Lb libposix 204which is also be brought into scope if any of the 205.Dv _POSIX_SOURCE , 206.Dv _POSIX_C_SOURCE 207or 208.Dv _XOPEN_SOURCE 209preprocessor symbols are defined at compile-time: 210the 211.Fn rename 212function conforms to 213.St -p1003.1-90 214and 215.St -xpg4.2 . 216.Sh BUGS 217The system can deadlock if a loop in the file system graph is present. 218This loop takes the form of an entry in directory 219.Ql Pa a , 220say 221.Ql Pa a/foo , 222being a hard link to directory 223.Ql Pa b , 224and an entry in 225directory 226.Ql Pa b , 227say 228.Ql Pa b/bar , 229being a hard link 230to directory 231.Ql Pa a . 232When such a loop exists and two separate processes attempt to 233perform 234.Ql rename a/foo b/bar 235and 236.Ql rename b/bar a/foo , 237respectively, 238the system may deadlock attempting to lock 239both directories for modification. 240Hard links to directories should be 241replaced by symbolic links by the system administrator. 242