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