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