1.\" Copyright (c) 1983, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)rename.2 6.7 (Berkeley) 3/10/91 33.\" 34.Dd March 10, 1991 35.Dt RENAME 2 36.Os BSD 4.2 37.Sh NAME 38.Nm rename 39.Nd change the name of a file 40.Sh SYNOPSIS 41.Fd #include <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.Sh CAVEAT 72The system can deadlock if a loop in the file system graph is present. 73This loop takes the form of an entry in directory 74.Ql Pa a , 75say 76.Ql Pa a/foo , 77being a hard link to directory 78.Ql Pa b , 79and an entry in 80directory 81.Ql Pa b , 82say 83.Ql Pa b/bar , 84being a hard link 85to directory 86.Ql Pa a . 87When such a loop exists and two separate processes attempt to 88perform 89.Ql rename a/foo b/bar 90and 91.Ql rename b/bar a/foo , 92respectively, 93the system may deadlock attempting to lock 94both directories for modification. 95Hard links to directories should be 96replaced by symbolic links by the system administrator. 97.Sh RETURN VALUES 98A 0 value is returned if the operation succeeds, otherwise 99.Fn rename 100returns -1 and the global variable 101.Va errno 102indicates the reason for the failure. 103.Sh ERRORS 104.Fn Rename 105will fail and neither of the argument files will be 106affected if: 107.Bl -tag -width ENAMETOOLONG 108.It Bq Er EINVAL 109Either pathname contains a character with the high-order bit set. 110.It Bq Er ENAMETOOLONG 111A component of either pathname exceeded 255 characters, 112or the entire length of either path name exceeded 1023 characters. 113.It Bq Er ENOENT 114A component of the 115.Fa from 116path does not exist, 117or a path prefix of 118.Fa to 119does not exist. 120.It Bq Er EACCES 121A component of either path prefix denies search permission. 122.It Bq Er EACCES 123The requested link requires writing in a directory with a mode 124that denies write permission. 125.It Bq Er EPERM 126The directory containing 127.Fa from 128is marked sticky, 129and neither the containing directory nor 130.Fa from 131are owned by the effective user ID. 132.It Bq Er EPERM 133The 134.Fa to 135file exists, 136the directory containing 137.Fa to 138is marked sticky, 139and neither the containing directory nor 140.Fa to 141are owned by the effective user ID. 142.It Bq Er ELOOP 143Too many symbolic links were encountered in translating either pathname. 144.It Bq Er ENOTDIR 145A component of either path prefix is not a directory. 146.It Bq Er ENOTDIR 147.Fa from 148is a directory, but 149.Fa to 150is not a directory. 151.It Bq Er EISDIR 152.Fa to 153is a directory, but 154.Fa from 155is not a directory. 156.It Bq Er EXDEV 157The link named by 158.Fa to 159and the file named by 160.Fa from 161are on different logical devices (file systems). Note that this error 162code will not be returned if the implementation permits cross-device 163links. 164.It Bq Er ENOSPC 165The directory in which the entry for the new name is being placed 166cannot be extended because there is no space left on the file 167system containing the directory. 168.It Bq Er EDQUOT 169The directory in which the entry for the new name 170is being placed cannot be extended because the 171user's quota of disk blocks on the file system 172containing the directory has been exhausted. 173.It Bq Er EIO 174An I/O error occurred while making or updating a directory entry. 175.It Bq Er EROFS 176The requested link requires writing in a directory on a read-only file 177system. 178.It Bq Er EFAULT 179.Em Path 180points outside the process's allocated address space. 181.It Bq Er EINVAL 182.Fa From 183is a parent directory of 184.Fa to , 185or an attempt is made to rename 186.Ql \&. 187or 188.Ql \&.. . 189.It Bq Er ENOTEMPTY 190.Fa To 191is a directory and is not empty. 192.El 193.Sh SEE ALSO 194.Xr open 2 195.Sh STANDARDS 196.Fn Rename 197conforms to IEEE Std 1003.1-1988 198.Pq Dq Tn POSIX . 199