1.\" Copyright (c) 1983, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)rename.2 6.8 (Berkeley) 07/27/92 7.\" 8.Dd 9.Dt RENAME 2 10.Os BSD 4.2 11.Sh NAME 12.Nm rename 13.Nd change the name of a file 14.Sh SYNOPSIS 15.Fd #include <stdio.h> 16.Ft int 17.Fn rename "const char *from" "const char *to" 18.Sh DESCRIPTION 19.Fn Rename 20causes the link named 21.Fa from 22to be renamed as 23.Fa to . 24If 25.Fa to 26exists, it is first removed. 27Both 28.Fa from 29and 30.Fa to 31must be of the same type (that is, both directories or both 32non-directories), and must reside on the same file system. 33.Pp 34.Fn Rename 35guarantees that an instance of 36.Fa to 37will always exist, even if the system should crash in 38the middle of the operation. 39.Pp 40If the final component of 41.Fa from 42is a symbolic link, 43the symbolic link is renamed, 44not the file or directory to which it points. 45.Sh CAVEAT 46The system can deadlock if a loop in the file system graph is present. 47This loop takes the form of an entry in directory 48.Ql Pa a , 49say 50.Ql Pa a/foo , 51being a hard link to directory 52.Ql Pa b , 53and an entry in 54directory 55.Ql Pa b , 56say 57.Ql Pa b/bar , 58being a hard link 59to directory 60.Ql Pa a . 61When such a loop exists and two separate processes attempt to 62perform 63.Ql rename a/foo b/bar 64and 65.Ql rename b/bar a/foo , 66respectively, 67the system may deadlock attempting to lock 68both directories for modification. 69Hard links to directories should be 70replaced by symbolic links by the system administrator. 71.Sh RETURN VALUES 72A 0 value is returned if the operation succeeds, otherwise 73.Fn rename 74returns -1 and the global variable 75.Va errno 76indicates the reason for the failure. 77.Sh ERRORS 78.Fn Rename 79will fail and neither of the argument files will be 80affected if: 81.Bl -tag -width ENAMETOOLONG 82.It Bq Er EINVAL 83Either pathname contains a character with the high-order bit set. 84.It Bq Er ENAMETOOLONG 85A component of either pathname exceeded 255 characters, 86or the entire length of either path name exceeded 1023 characters. 87.It Bq Er ENOENT 88A component of the 89.Fa from 90path does not exist, 91or a path prefix of 92.Fa to 93does not exist. 94.It Bq Er EACCES 95A component of either path prefix denies search permission. 96.It Bq Er EACCES 97The requested link requires writing in a directory with a mode 98that denies write permission. 99.It Bq Er EPERM 100The directory containing 101.Fa from 102is marked sticky, 103and neither the containing directory nor 104.Fa from 105are owned by the effective user ID. 106.It Bq Er EPERM 107The 108.Fa to 109file exists, 110the directory containing 111.Fa to 112is marked sticky, 113and neither the containing directory nor 114.Fa to 115are owned by the effective user ID. 116.It Bq Er ELOOP 117Too many symbolic links were encountered in translating either pathname. 118.It Bq Er ENOTDIR 119A component of either path prefix is not a directory. 120.It Bq Er ENOTDIR 121.Fa from 122is a directory, but 123.Fa to 124is not a directory. 125.It Bq Er EISDIR 126.Fa to 127is a directory, but 128.Fa from 129is not a directory. 130.It Bq Er EXDEV 131The link named by 132.Fa to 133and the file named by 134.Fa from 135are on different logical devices (file systems). Note that this error 136code will not be returned if the implementation permits cross-device 137links. 138.It Bq Er ENOSPC 139The directory in which the entry for the new name is being placed 140cannot be extended because there is no space left on the file 141system containing the directory. 142.It Bq Er EDQUOT 143The directory in which the entry for the new name 144is being placed cannot be extended because the 145user's quota of disk blocks on the file system 146containing the directory has been exhausted. 147.It Bq Er EIO 148An I/O error occurred while making or updating a directory entry. 149.It Bq Er EROFS 150The requested link requires writing in a directory on a read-only file 151system. 152.It Bq Er EFAULT 153.Em Path 154points outside the process's allocated address space. 155.It Bq Er EINVAL 156.Fa From 157is a parent directory of 158.Fa to , 159or an attempt is made to rename 160.Ql \&. 161or 162.Ql \&.. . 163.It Bq Er ENOTEMPTY 164.Fa To 165is a directory and is not empty. 166.El 167.Sh SEE ALSO 168.Xr open 2 169.Xr symlink 7 170.Sh STANDARDS 171.Fn Rename 172conforms to IEEE Std 1003.1-1988 173.Pq Dq Tn POSIX . 174