1.\" $NetBSD: rename.2,v 1.7 1995/02/27 12:36:15 cgd Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)rename.2 8.1 (Berkeley) 6/4/93 35.\" 36.Dd June 3, 2021 37.Dt RENAME 2 38.Os BSD 4.2 39.Sh NAME 40.Nm rename , 41.Nm renameat , 42.Nm renamex_np , 43.Nm renameatx_np 44.Nd change the name of a file 45.Sh SYNOPSIS 46.Fd #include <stdio.h> 47.Ft int 48.Fo rename 49.Fa "const char *old" 50.Fa "const char *new" 51.Fc 52.Ft int 53.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" 54.Ft int 55.Fn renamex_np "const char *from" "const char *to" "unsigned int flags" 56.Ft int 57.Fn renameatx_np "int fromfd" "const char *from" "int tofd" "const char *to" "unsigned int flags" 58.Sh DESCRIPTION 59The 60.Fn rename 61system call causes the link named 62.Fa old 63to be renamed as 64.Fa new . 65If 66.Fa new 67exists, it is first removed. 68Both 69.Fa old 70and 71.Fa new 72must be of the same type 73(that is, both must be either directories or non-directories) 74and must reside on the same file system. 75.Pp 76The 77.Fn rename 78system call guarantees that an instance of 79.Fa new 80will always exist, 81even if the system should crash in the middle of the operation. 82.Pp 83If the final component of 84.Fa old 85is a symbolic link, 86the symbolic link is renamed, 87not the file or directory to which it points. 88.Pp 89The 90.Fn renameat 91system call is equivalent to 92.Fn rename 93except in the case where either 94.Fa from 95or 96.Fa to 97specifies a relative path. 98If 99.Fa from 100is a relative path, the file to be renamed is located 101relative to the directory associated with the file descriptor 102.Fa fromfd 103instead of the current working directory. 104If the 105.Fa to 106is a relative path, the same happens only relative to the directory associated 107with 108.Fa tofd . 109If the 110.Fn renameat 111is passed the special value 112.Dv AT_FDCWD 113in the 114.Fa fromfd 115or 116.Fa tofd 117parameter, the current working directory is used in the determination 118of the file for the respective path parameter. 119.Pp 120The 121.Fn renamex_np 122and 123.Fn renameatx_np 124system calls are similar to their counterparts except that they take a 125.Fa flags 126argument. 127Values for 128.Fa flags 129are constructed with below bits set: 130.Bl -tag -offset indent 131.It Dv RENAME_SWAP 132On file systems that support it (see 133.Xr getattrlist 2 134.Dv VOL_CAP_INT_RENAME_SWAP Ns ), 135it will cause the source and target to be atomically swapped. Source and target need not be of 136the same type, i.e. it is possible to swap a file with a directory. 137EINVAL is returned in case of bitwise-inclusive OR with 138.Dv RENAME_EXCL . 139.It Dv RENAME_EXCL 140On file systems that support it (see 141.Xr getattrlist 2 142.Dv VOL_CAP_INT_RENAME_EXCL Ns ), 143it will cause 144.Dv EEXIST 145to be returned if the destination already exists. EINVAL is returned in case of bitwise-inclusive OR with 146.Dv RENAME_SWAP . 147.It Dv RENAME_NOFOLLOW_ANY 148If any symbolic links are encountered during pathname resolution, an error is returned. 149.El 150.Sh CAVEATS 151The system can deadlock if a loop is present in the file system graph. 152This loop takes the form of an entry in directory 153.Ql Pa a , 154say 155.Ql Pa a/foo , 156being a hard link to directory 157.Ql Pa b , 158and an entry in 159directory 160.Ql Pa b , 161say 162.Ql Pa b/bar , 163being a hard link 164to directory 165.Ql Pa a . 166When such a loop exists and two separate processes attempt to 167perform 168.Ql rename a/foo b/bar 169and 170.Ql rename b/bar a/foo , 171respectively, 172the system may deadlock attempting to lock 173both directories for modification. 174.Pp 175Whether or not hard links to directories are supported is specific to 176the underlying filesystem implementation. 177.Pp 178It is recommended that any hard links to directories in an underlying 179filesystem should be replaced by symbolic links by the system administrator 180to avoid the possibility of deadlocks. 181.Pp 182Moving or renaming a file or directory into a directory with inheritable ACLs does not result in ACLs being set on the file or directory. Use 183.Xr acl 3 184in conjunction with 185.Fn rename 186to set ACLs on the file or directory. 187.Sh RETURN VALUES 188A 0 value is returned if the operation succeeds, otherwise 189.Fn rename 190returns -1 and the global variable 191.Va errno 192indicates the reason for the failure. 193.Sh ERRORS 194The 195.Fn rename 196system call will fail and neither of the argument files will be 197affected if: 198.Bl -tag -width Er 199.\" =========== 200.It Bq Er EACCES 201A component of either path prefix denies search permission. 202.\" =========== 203.It Bq Er EACCES 204The requested operation requires writing in a directory 205(e.g., 206.Fa new , 207new/.., or old/..) whose modes disallow this. 208.\" =========== 209.It Bq Er EACCES 210.Fa old 211is a directory and it, or some descendent in the namespace, is open 212and the file system format does does not support renaming a directory 213with open descendents (see 214.Xr getattrlist 2 215.Dv VOL_CAP_INT_RENAME_OPENFAIL Ns ). 216.\" =========== 217.It Bq Er EDQUOT 218The directory in which the entry for the new name 219is being placed cannot be extended because the 220user's quota of disk blocks on the file system 221containing the directory has been exhausted. 222.\" =========== 223.It Bq Er EEXIST 224.Fa flags 225has 226.Dv RENAME_EXCL 227set but 228.Fa new 229already exists. 230.\" =========== 231.It Bq Er EFAULT 232.Em Path 233points outside the process's allocated address space. 234.\" =========== 235.It Bq Er EINVAL 236.Fa Old 237is a parent directory of 238.Fa new , 239or an attempt is made to rename 240.Ql \&. 241or 242.Ql \&.. . 243If 244.Dv RENAME_SWAP 245is used, then 246.Dv EINVAL 247will also be returned if 248.Fa new 249is a parent directory of 250.Fa old . 251If both RENAME_SWAP and RENAME_EXCL bits are set in 252.Fa flags , 253then 254.Dv EINVAL 255will be returned. 256.\" =========== 257.It Bq Er EINVAL 258.Fa flags 259has an invalid value. 260.\" =========== 261.It Bq Er EIO 262An I/O error occurs while making or updating a directory entry. 263.\" =========== 264.It Bq Er EISDIR 265.Fa new 266is a directory, but 267.Fa old 268is not a directory. 269.\" =========== 270.It Bq Er ELOOP 271Too many symbolic links are encountered in translating either pathname. 272This is taken to be indicative of a looping symbolic link. 273.\" =========== 274.It Bq Er ELOOP 275If RENAME_NOFOLLOW_ANY was passed and a symbolic link was encountered in 276translating either pathname. 277.\" =========== 278.It Bq Er ENAMETOOLONG 279A component of a pathname exceeds 280.Dv {NAME_MAX} 281characters, or an entire path name exceeds 282.Dv {PATH_MAX} 283characters. 284.\" =========== 285.It Bq Er ENOENT 286A component of the 287.Fa old 288path does not exist, 289or a path prefix of 290.Fa new 291does not exist. 292.\" =========== 293.It Bq Er ENOENT 294.Fa flags 295has 296.Dv RENAME_SWAP 297set but 298.Fa new 299does not exist. 300.\" =========== 301.It Bq Er ENOSPC 302The directory in which the entry for the new name is being placed 303cannot be extended because there is no space left on the file 304system containing the directory. 305.\" =========== 306.It Bq Er ENOTDIR 307A component of either path prefix is not a directory. 308.\" =========== 309.It Bq Er ENOTDIR 310.Fa old 311is a directory, but 312.Fa new 313is not a directory. 314.\" =========== 315.It Bq Er ENOTEMPTY 316.Fa New 317is a directory and is not empty. 318.\" =========== 319.It Bq Er ENOTSUP 320.Fa flags 321has a value that is not supported by the file system. 322.\" =========== 323.It Bq Er EPERM 324The directory containing 325.Fa old 326is marked sticky, 327and neither the containing directory nor 328.Fa old 329are owned by the effective user ID. 330.\" =========== 331.It Bq Er EPERM 332The 333.Fa new 334file exists, 335the directory containing 336.Fa new 337is marked sticky, 338and neither the containing directory nor 339.Fa new 340are owned by the effective user ID. 341.\" =========== 342.It Bq Er EROFS 343The requested link requires writing in a directory on a read-only file 344system. 345.\" =========== 346.It Bq Er EXDEV 347The link named by 348.Fa new 349and the file named by 350.Fa old 351are on different logical devices (file systems). 352Note that this error code will not be returned 353if the implementation permits cross-device links. 354.\" =========== 355.It Bq Er EDEADLK 356A component of either pathname refers to a 357.Dq dataless 358directory that requires materialization and the I/O policy of the current 359thread or process disallows dataless directory materialization 360.Po see 361.Xr getiopolicy_np 3 362.Pc . 363.\" =========== 364.It Bq Er EDEADLK 365The 366.Fa from 367pathname refers to a 368.Dq dataless 369file or directory that must be materialized before being moved to its new 370location and the I/O policy of the current thread or process disallows file 371or directory materialization 372.Po see 373.Xr getiopolicy_np 3 374.Pc . 375.El 376.Pp 377The 378.Fn renameat 379and 380.Fn renameatx_np 381calls may also fail with: 382.Bl -tag -width Er 383.It Bq Er EBADF 384The 385.Fa from 386argument does not specify an absolute path and the 387.Fa fromfd 388argument is neither 389.Dv AT_FDCWD 390nor a valid file descriptor open for searching, or the 391.Fa to 392argument does not specify an absolute path and the 393.Fa tofd 394argument is neither 395.Dv AT_FDCWD 396nor a valid file descriptor open for searching. 397.It Bq Er ENOTDIR 398The 399.Fa from 400argument is not an absolute path and 401.Fa fromfd 402is neither 403.Dv AT_FDCWD 404nor a file descriptor associated with a directory, or the 405.Fa to 406argument is not an absolute path and 407.Fa tofd 408is neither 409.Dv AT_FDCWD 410nor a file descriptor associated with a directory. 411.El 412.Sh CONFORMANCE 413The restriction on renaming a directory whose permissions disallow writing 414is based on the fact that UFS directories contain a ".." entry. 415If renaming a directory would move it to another parent directory, 416this entry needs to be changed. 417.Pp 418This restriction has been generalized to disallow renaming 419of any write-disabled directory, 420even when this would not require a change to the ".." entry. 421For consistency, HFS+ directories emulate this behavior. 422.Sh SEE ALSO 423.Xr open 2 , 424.Xr symlink 7 425.Sh STANDARDS 426The 427.Fn rename 428function conforms to 429.St -p1003.1-88 . 430The 431.Fn renameat 432system call is expected to conform to POSIX.1-2008 . 433