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.\" 35.Dd July 31, 2010 36.Dt RENAME 2 37.Os 38.Sh NAME 39.Nm rename 40.Nd change the name of a file 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In stdio.h 45.Ft int 46.Fn rename "const char *from" "const char *to" 47.Ft int 48.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" 49.Sh DESCRIPTION 50.Fn Rename 51causes the link named 52.Fa from 53to be renamed as 54.Fa to . 55If 56.Fa to 57exists, it is first removed. 58Both 59.Fa from 60and 61.Fa to 62must be of the same type (that is, both directories or both 63non-directories), and must reside on the same file system. 64.Pp 65.Fn Rename 66guarantees that if 67.Fa to 68already exists, an instance of 69.Fa to 70will always exist, even if the system should crash in 71the middle of the operation. 72.Pp 73If the final component of 74.Fa from 75is a symbolic link, 76the symbolic link is renamed, 77not the file or directory to which it points. 78.Pp 79The 80.Fn renameat 81system call is equivalent to 82.Fn rename 83except in the case where either 84.Fa from 85or 86.Fa to 87specifies a relative path. 88If 89.Fa from 90is a relative path, the file to be renamed is located 91relative to the directory associated with the file descriptor 92.Fa fromfd 93instead of the current working directory. 94If the 95.Fa to 96is a relative path, the same happens only relative to the directory associated 97with 98.Fa tofd . 99If the 100.Fn renameat 101is passed the special value 102.Dv AT_FDCWD 103in the 104.Fa fromfd 105or 106.Fa tofd 107parameter, the current working directory is used in the determination 108of the file for the respective path parameter. 109.\".Sh CAVEAT 110.\"The system can deadlock if a loop in the file system graph is present. 111.\"This loop takes the form of an entry in directory 112.\".Ql Pa a , 113.\"say 114.\".Ql Pa a/foo , 115.\"being a hard link to directory 116.\".Ql Pa b , 117.\"and an entry in 118.\"directory 119.\".Ql Pa b , 120.\"say 121.\".Ql Pa b/bar , 122.\"being a hard link 123.\"to directory 124.\".Ql Pa a . 125.\"When such a loop exists and two separate processes attempt to 126.\"perform 127.\".Ql rename a/foo b/bar 128.\"and 129.\".Ql rename b/bar a/foo , 130.\"respectively, 131.\"the system may deadlock attempting to lock 132.\"both directories for modification. 133.\"Hard links to directories should be 134.\"replaced by symbolic links by the system administrator. 135.Sh RETURN VALUES 136.Rv -std rename 137.Sh ERRORS 138.Fn Rename 139will fail and neither of the argument files will be 140affected if: 141.Bl -tag -width Er 142.It Bq Er ENAMETOOLONG 143A component of either pathname exceeded 255 characters, 144or the entire length of either path name exceeded 1023 characters. 145.It Bq Er ENOENT 146A component of the 147.Fa from 148path does not exist, 149or a path prefix of 150.Fa to 151does not exist. 152.It Bq Er EACCES 153A component of either path prefix denies search permission. 154.It Bq Er EACCES 155The requested link requires writing in a directory with a mode 156that denies write permission. 157.It Bq Er EPERM 158The directory containing 159.Fa from 160is marked sticky, 161and neither the containing directory nor 162.Fa from 163are owned by the effective user ID. 164.It Bq Er EPERM 165The 166.Fa to 167file exists, 168the directory containing 169.Fa to 170is marked sticky, 171and neither the containing directory nor 172.Fa to 173are owned by the effective user ID. 174.It Bq Er ELOOP 175Too many symbolic links were encountered in translating either pathname. 176.It Bq Er ENOTDIR 177A component of either path prefix is not a directory. 178.It Bq Er ENOTDIR 179.Fa from 180is a directory, but 181.Fa to 182is not a directory. 183.It Bq Er EISDIR 184.Fa to 185is a directory, but 186.Fa from 187is not a directory. 188.It Bq Er EXDEV 189The link named by 190.Fa to 191and the file named by 192.Fa from 193are on different logical devices (file systems). Note that this error 194code will not be returned if the implementation permits cross-device 195links. 196.It Bq Er ENOSPC 197The directory in which the entry for the new name is being placed 198cannot be extended because there is no space left on the file 199system containing the directory. 200.It Bq Er EDQUOT 201The directory in which the entry for the new name 202is being placed cannot be extended because the 203user's quota of disk blocks on the file system 204containing the directory has been exhausted. 205.It Bq Er EIO 206An I/O error occurred while making or updating a directory entry. 207.It Bq Er EROFS 208The requested link requires writing in a directory on a read-only file 209system. 210.It Bq Er EFAULT 211.Em Path 212points outside the process's allocated address space. 213.It Bq Er EINVAL 214.Fa From 215is a parent directory of 216.Fa to , 217or an attempt is made to rename 218.Ql .\& 219or 220.Ql \&.. . 221.It Bq Er ENOTEMPTY 222.Fa To 223is a directory and is not empty. 224.El 225.Pp 226In addition to the errors returned by the 227.Fn rename , 228the 229.Fn renameat 230may fail if: 231.Bl -tag -width Er 232.It Bq Er EBADF 233The 234.Fa from 235argument does not specify an absolute path and the 236.Fa fromfd 237argument is neither 238.Dv AT_FDCWD 239nor a valid file descriptor open for searching, or the 240.Fa to 241argument does not specify an absolute path and the 242.Fa tofd 243argument is neither 244.Dv AT_FDCWD 245nor a valid file descriptor open for searching. 246.It Bq Er ENOTDIR 247The 248.Fa from 249argument is not an absolute path and 250.Fa fromfd 251is neither 252.Dv AT_FDCWD 253nor a file descriptor associated with a directory, or the 254.Fa to 255argument is not an absolute path and 256.Fa tofd 257is neither 258.Dv AT_FDCWD 259nor a file descriptor associated with a directory. 260.El 261.Sh SEE ALSO 262.Xr open 2 , 263.Xr symlink 7 264.Sh STANDARDS 265The 266.Fn rename 267system call is expected to conform to 268.St -p1003.1-96 . 269The 270.Fn renameat 271system call follows The Open Group Extended API Set 2 specification. 272.Sh HISTORY 273The 274.Fn renameat 275system call appeared in 276.Dx 2.7 . 277