1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. 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 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD: src/lib/libc/sys/rename.2,v 1.8.2.7 2001/12/14 18:34:01 ru Exp $ 34.\" $DragonFly: src/lib/libc/sys/rename.2,v 1.2 2003/06/17 04:26:47 dillon Exp $ 35.\" 36.Dd June 4, 1993 37.Dt RENAME 2 38.Os 39.Sh NAME 40.Nm rename 41.Nd change the name of a file 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In stdio.h 46.Ft int 47.Fn rename "const char *from" "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 if 66.Fa to 67already exists, an instance of 68.Fa to 69will always exist, even if the system should crash in 70the middle of the operation. 71.Pp 72If the final component of 73.Fa from 74is a symbolic link, 75the symbolic link is renamed, 76not the file or directory to which it points. 77.\".Sh CAVEAT 78.\"The system can deadlock if a loop in the file system graph is present. 79.\"This loop takes the form of an entry in directory 80.\".Ql Pa a , 81.\"say 82.\".Ql Pa a/foo , 83.\"being a hard link to directory 84.\".Ql Pa b , 85.\"and an entry in 86.\"directory 87.\".Ql Pa b , 88.\"say 89.\".Ql Pa b/bar , 90.\"being a hard link 91.\"to directory 92.\".Ql Pa a . 93.\"When such a loop exists and two separate processes attempt to 94.\"perform 95.\".Ql rename a/foo b/bar 96.\"and 97.\".Ql rename b/bar a/foo , 98.\"respectively, 99.\"the system may deadlock attempting to lock 100.\"both directories for modification. 101.\"Hard links to directories should be 102.\"replaced by symbolic links by the system administrator. 103.Sh RETURN VALUES 104.Rv -std rename 105.Sh ERRORS 106.Fn Rename 107will fail and neither of the argument files will be 108affected if: 109.Bl -tag -width Er 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.Xr symlink 7 196.Sh STANDARDS 197The 198.Fn rename 199function call is expected to conform to 200.St -p1003.1-96 . 201